Mode Enforcement

ChameleonDB uses Integrity Modes to control schema modifications through a Unix-style protection ring system.

The 4 Integrity Modes

Mode	Ring	Use Case	Schema Changes
readonly	R3	Production (default)	❌ Blocked
standard	R2	Development teams	✅ Controlled
privileged	R1	DBAs	✅ Direct (logged)
emergency	R0	Incident recovery	✅ No checks (audited)

Modes are inspired by CPU protection rings (Ring 0-3), where higher numbers = more restrictions.

Mode Details

readonly (R3) - Production Default

Purpose: Lock schemas in production to prevent accidental changes. Permissions:

❌ Schema migrations blocked
✅ Read-only operations allowed
✅ Query execution
✅ Data mutations (INSERT/UPDATE/DELETE)

Example:

# Try to migrate in readonly mode
chameleon migrate --apply

❌ readonly mode: schema modifications blocked
💡 Upgrade to standard mode: chameleon config set mode=standard

This is the recommended mode for production environments. Schema changes should go through proper change management processes.

standard (R2) - Development Teams

Purpose: Allow controlled schema changes during development. Permissions:

✅ Schema migrations allowed (with validation)
✅ Migration preview (dry-run)
✅ Schema validation
✅ All operations logged

Example:

# Upgrade to standard mode
chameleon config set mode=standard
🔐 Enter mode password: ****
✅ Mode upgraded to standard

# Now migrations work
chameleon migrate --apply
✅ Migration applied successfully
✅ Schema v002 registered and locked

Recommended for development and staging environments where teams need to iterate on schemas.

privileged (R1) - Database Administrators

Purpose: Direct schema access for DBAs with full logging. Permissions:

✅ Direct SQL execution
✅ Bypass certain safety checks
✅ Manual schema registration
✅ All operations audited

Example:

# Upgrade to privileged mode
chameleon config set mode=privileged
🔐 Enter mode password: ****
✅ Mode upgraded to privileged

# Execute direct SQL (logged)
chameleon exec "ALTER TABLE users ADD COLUMN admin BOOLEAN DEFAULT FALSE"
⚠️  Direct SQL in privileged mode
✅ Executed successfully
📝 Logged to audit trail

Use sparingly. Only for experienced DBAs who need direct database access. All operations are logged for audit.

emergency (R0) - Incident Recovery

Purpose: Unrestricted access for emergency situations. Permissions:

✅ Skip integrity checks
✅ Force migrations
✅ Bypass all safety guards
✅ Complete audit trail

Example:

# Upgrade to emergency mode
chameleon config set mode=emergency
🔐 Enter mode password: ****
⚠️  WARNING: Emergency mode bypasses all safety checks
✅ Mode upgraded to emergency

# Force migration without checks
chameleon migrate --apply --force
⚠️  EMERGENCY: Skipping integrity verification
⚠️  EMERGENCY: Skipping migration validation
✅ Migration forced
📝 Emergency operation logged

Use ONLY during incidents. This mode bypasses all safety mechanisms. Every action is fully audited.

Mode Upgrades & Downgrades

Password Protection

Mode upgrades (lower ring → higher privilege) require password authentication:

# Set password (do this first)
chameleon config auth set-password

Enter new password: ********
Confirm password: ********
✅ Mode password configured

Password is stored:

.chameleon/vault/auth/mode.key  # Hashed password

Set file permissions: chmod 600 .chameleon/vault/auth/mode.key

Upgrade Mode (Requires Password)

# readonly → standard
chameleon config set mode=standard
🔐 Enter mode password: ****
✅ Mode upgraded to standard

# standard → privileged
chameleon config set mode=privileged
🔐 Enter mode password: ****
✅ Mode upgraded to privileged

# privileged → emergency
chameleon config set mode=emergency
🔐 Enter mode password: ****
⚠️  WARNING: Emergency mode bypasses all safety checks
✅ Mode upgraded to emergency

Downgrade Mode (No Password)

Mode downgrades (higher privilege → lower ring) don’t require a password:

# emergency → readonly (no password)
chameleon config set mode=readonly
✅ Mode downgraded to readonly

# privileged → standard (no password)
chameleon config set mode=standard
✅ Mode downgraded to standard

Downgrades are unrestricted because they increase security, not decrease it.