Managing Integrity Modes

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:

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:

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:

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

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

Set password immediately

Configure a mode password right after initializing:

chameleon init
chameleon config auth set-password

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

Secure password storage

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

​Overview

​Mode Descriptions

​readonly (R3) — Production Default

​standard (R2) — Development Teams

​privileged (R1) — Database Administrators

​emergency (R0) — Incident Recovery

​Password Protection

​Setting a Mode Password

​Password Storage

​Mode Management Workflow

​Check Current Mode

​Upgrade Mode (Requires Password)

​Downgrade Mode (No Password Required)

​Complete Examples

​Development Workflow

​Production Deployment

​Authorized Schema Change in Production

​Audit Trail

​Mode Enforcement

​Operations Blocked in readonly Mode

​Operations Allowed in standard Mode

​Common Workflows

​Local Development

​CI/CD Pipeline

​Staging Environment

​Security Best Practices

​Common Issues

​”mode password not set”

​“invalid password”

​“readonly mode: blocked”

​Forgot password

​Next Steps

Migration Workflow

Introspection

Security Model

Architecture

Overview

Mode Descriptions

readonly (R3) — Production Default

standard (R2) — Development Teams

privileged (R1) — Database Administrators

emergency (R0) — Incident Recovery

Password Protection

Setting a Mode Password

Password Storage

Mode Management Workflow

Check Current Mode

Upgrade Mode (Requires Password)

Downgrade Mode (No Password Required)

Complete Examples

Development Workflow

Production Deployment

Authorized Schema Change in Production

Audit Trail

Mode Enforcement

Operations Blocked in readonly Mode

Operations Allowed in standard Mode

Common Workflows

Local Development

CI/CD Pipeline

Staging Environment

Security Best Practices

Common Issues

”mode password not set”

“invalid password”

“readonly mode: blocked”

Forgot password

Next Steps