Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chameleondb.dev/llms.txt

Use this file to discover all available pages before exploring further.

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:
ModeRingUse CaseSchema ChangesPassword Required
readonlyR3Production (default)❌ BlockedTo upgrade
standardR2Development teams✅ ControlledTo upgrade
privilegedR1DBAs✅ Direct (logged)To upgrade
emergencyR0Incident 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: 
Current mode: readonly
Or use status for comprehensive info: 
chameleon status
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:
1

Set Password (First Time Only)

chameleon config auth set-password
Enter new password: ********
✅ Mode password configured
2

Upgrade Mode

chameleon config set mode=standard
Interactive prompt:
🔐 Enter mode password: ****
✅ Mode upgraded to standard
3

Verify Mode Change

chameleon config get mode
Output:
Current mode: standard

​
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

OperationCommandBehavior
Migrationchameleon migrate --apply❌ Blocked
Introspectionchameleon introspect❌ Blocked
Validationchameleon validate✅ Allowed
Status checkchameleon status✅ Allowed
Verify integritychameleon verify✅ Allowed

​
Operations Allowed in standard Mode

OperationCommandBehavior
Migrationchameleon migrate --apply✅ Allowed (with vault registration)
Introspectionchameleon 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

Configure a mode password right after initializing:
chameleon init
chameleon config auth set-password
Always deploy production with readonly mode:
chameleon config set mode=readonly
Upgrade, apply changes, then immediately downgrade:
chameleon config set mode=standard
chameleon migrate --apply
chameleon config set mode=readonly  # ← Do this immediately
Review integrity log for unauthorized access:
cat .chameleon/vault/integrity.log | grep MODE
Never commit passwords to version control:
echo ".chameleon/" >> .gitignore
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