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
Migration Workflow Apply schema changes with proper modes
Introspection Generate schemas (requires standard mode)
Security Model Complete security architecture
Architecture Understand the integrity system