Integrity Modes provide Unix-style protection rings for schema governance, enabling explicit control over who can modify schemas and when.
Overview ChameleonDB enforces schema changes through four integrity modes , each with different permission levels:
Mode Ring Use Case Schema Changes Password Required readonly R3 Production (default) ❌ Blocked To upgrade standard R2 Development teams ✅ Controlled To upgrade privileged R1 DBAs ✅ Direct (logged) To upgrade emergency R0 Incident recovery ✅ No checks (audited) To upgrade
Mode upgrades (e.g., readonly → standard) require password authentication .Mode downgrades (e.g., standard → readonly) do NOT require password .
Mode Descriptions readonly (R3) — Production Default Purpose: Lock schema changes in production environments.Behavior:
❌ Migrations blocked
❌ Introspection blocked
✅ Queries allowed
✅ Reads from Schema Vault
Use case: Production databases where schema changes should never happen without explicit authorization.# Attempt migration in readonly mode $ chameleon migrate --apply ❌ readonly mode: schema modifications blocked 💡 Upgrade mode: chameleon config set mode=standard
standard (R2) — Development Teams Purpose: Allow controlled schema changes for development workflows.Behavior:
✅ Migrations allowed (with vault registration)
✅ Introspection allowed
✅ Full audit trail
✅ Integrity verification enforced
Use case: Development and staging environments where teams actively iterate on schemas.# Migrations work in standard mode $ chameleon migrate --apply ✅ Schema v002 registered and applied
privileged (R1) — Database Administrators Purpose: Direct database access with comprehensive logging.Behavior:
✅ All standard operations
✅ Direct SQL execution (logged)
✅ Advanced recovery operations
Use case: DBAs who need direct database access while maintaining audit compliance.Privileged mode is planned for v1.1. In v1.0, use standard mode for DBA workflows.
emergency (R0) — Incident Recovery Purpose: Critical incident recovery with minimal checks.Behavior:
✅ All operations allowed
⚠️ Integrity checks skipped
📝 All actions heavily audited
Use case: Production outages requiring immediate schema fixes.Emergency mode is planned for v1.1. In v1.0, use privileged mode with caution.
Password Protection Setting a Mode Password Set a password to protect mode upgrades:
chameleon config auth set-password
Interactive prompt: Enter new password: ******** Confirm password: ******** ✅ Mode password configured
Set a mode password immediately after initializing your project to secure schema changes.
Password Storage Passwords are stored securely in:
.chameleon/vault/auth/password.hash
Hashed using bcrypt
Never stored in plaintext
Protected by OS file permissions (0600)
Add .chameleon/ to .gitignore to prevent committing passwords to version control.
Mode Management Workflow Check Current Mode View your current integrity mode:
chameleon config get mode
Output: Or use status for comprehensive info:
Output: Schema: Current version: v001 Status: ✓ Up to date Vault: Versions: 1 registered Integrity: ✓ OK Mode: 🔒 readonly (locked)
Upgrade Mode (Requires Password) Upgrading to a higher ring requires password authentication:
Set Password (First Time Only)
chameleon config auth set-password Enter new password: ******** ✅ Mode password configured
Upgrade Mode
chameleon config set mode=standard
Interactive prompt: 🔐 Enter mode password: **** ✅ Mode upgraded to standard
Verify Mode Change
chameleon config get mode
Output: Downgrade Mode (No Password Required) Downgrading to a lower ring does NOT require password:
chameleon config set mode=readonly
Output: ✅ Mode downgraded to readonly 💡 Schema modifications now blocked
Downgrades are intentionally password-free to make it easy to lock down production environments.
Complete Examples Development Workflow # Initialize project (defaults to readonly) chameleon init ✅ Vault initialized in readonly mode # Set password for future upgrades chameleon config auth set-password Enter new password: ******** ✅ Mode password configured # Upgrade to standard for development chameleon config set mode=standard 🔐 Enter mode password: **** ✅ Mode upgraded to standard # Now you can run migrations chameleon migrate --apply ✅ Schema v001 registered and applied # Lock down when deploying to production chameleon config set mode=readonly ✅ Mode downgraded to readonly
Production Deployment # Production should always start in readonly chameleon init ✅ Vault initialized in readonly mode # Set strong password chameleon config auth set-password Enter new password: ******** ✅ Mode password configured # Verify mode is readonly chameleon status Mode: 🔒 readonly (locked) # Any migration attempts will fail chameleon migrate --apply ❌ readonly mode: schema modifications blocked
Authorized Schema Change in Production # 1. Verify current state chameleon status Mode: 🔒 readonly (locked) # 2. Upgrade with authorization chameleon config set mode=standard 🔐 Enter mode password: **** ✅ Mode upgraded to standard # 3. Apply migration chameleon migrate --apply ✅ Schema v002 registered and applied # 4. Immediately lock back down chameleon config set mode=readonly ✅ Mode downgraded to readonly # 5. Verify in audit log cat .chameleon/vault/integrity.log
Audit Trail All mode changes are logged in the integrity log:
cat .chameleon/vault/integrity.log
Example log entries: 2026-03-03T10:30:00Z [MODE] readonly → standard (user: dperalta) 2026-03-03T10:35:00Z [MIGRATE] v001 → v002 (mode: standard) 2026-03-03T10:36:00Z [MODE] standard → readonly (user: dperalta)
Mode Enforcement Operations Blocked in readonly Mode Operation Command Behavior Migration chameleon migrate --apply❌ Blocked Introspection chameleon introspect❌ Blocked Validation chameleon validate✅ Allowed Status check chameleon status✅ Allowed Verify integrity chameleon verify✅ Allowed
Operations Allowed in standard Mode Operation Command Behavior Migration chameleon migrate --apply✅ Allowed (with vault registration) Introspection chameleon introspect✅ Allowed All readonly ops - ✅ Allowed
Common Workflows Local Development # Start in standard mode for active development chameleon config set mode=standard # Iterate freely chameleon migrate --apply # ... make changes ... chameleon migrate --apply
CI/CD Pipeline # In CI: upgrade temporarily, then lock down chameleon config set mode=standard <<< " $MODE_PASSWORD " chameleon migrate --apply chameleon config set mode=readonly
Staging Environment # Staging mirrors production: readonly by default chameleon config set mode=readonly # Upgrade only for authorized deployments chameleon config set mode=standard chameleon migrate --apply chameleon config set mode=readonly
Security Best Practices
Use readonly in production
Always deploy production with readonly mode: chameleon config set mode=readonly
Minimize time in elevated modes
Upgrade, apply changes, then immediately downgrade: chameleon config set mode=standard chameleon migrate --apply chameleon config set mode=readonly # ← Do this immediately
Audit mode changes regularly
Review integrity log for unauthorized access: cat .chameleon/vault/integrity.log | grep MODE
Never commit passwords to version control: echo ".chameleon/" >> .gitignore
Use environment variables in CI/CD
Pass passwords securely via encrypted secrets: echo " $MODE_PASSWORD " | chameleon config set mode=standard
Common Issues ”mode password not set” Solution: Set password first:chameleon config auth set-password
“invalid password” Solution: Re-enter correct password or reset:chameleon config auth set-password
“readonly mode: blocked” Solution: Upgrade mode with password:chameleon config set mode=standard
Forgot password Solution: Reset password file (loses protection):rm .chameleon/vault/auth/password.hash chameleon config auth set-password
Deleting the password hash removes mode protection. Only do this if you have proper authorization.
Next Steps