ChameleonDB migrations are tightly integrated with the Schema Vault, providing automatic versioning, integrity verification, and a complete audit trail for every schema change.
Overview Unlike traditional migration tools, ChameleonDB:
Automatically registers schema versions on every migration
Verifies integrity before applying changes
Enforces mode restrictions (readonly blocks migrations)
Maintains an append-only audit trail
Enables migration recovery for failed attempts
Migration Commands Check Migration Status View the current state of your database and schema:
Output: Schema: Current version: v001 Status: ✓ Up to date Vault: Versions: 1 registered Integrity: ✓ OK Mode: 🔒 readonly (locked)
Preview Changes Check what changes will be applied without executing them:
This command:
Compares your schema.cham with the current database state
Shows a diff of detected changes
Does NOT apply migrations
Dry Run (View Generated SQL) See the exact SQL that will be executed:
chameleon migrate --dry-run
Output: 📋 Migration Preview: ───────────────────────────────────────────────── ALTER TABLE users ADD COLUMN age INTEGER; CREATE INDEX idx_users_age ON users(age); ───────────────────────────────────────────────── 💡 This is a dry run. Use --apply to execute.
Apply Migration Apply the migration to your database:
chameleon migrate --apply
The first time you run chameleon migrate --apply, it automatically initializes the Schema Vault and registers your schema as v001.
Complete Migration Workflow
Modify Your Schema
Edit your schema.cham file to add, remove, or modify entities and fields: entity User { id : uuid primary , email : string unique , name : string , age : int , // ← New field }
Validate Schema Syntax
Ensure your schema is syntactically correct: Output: ✅ Schema validated successfully Entities: 1 (User) Fields: 4
Preview Migration
Check what changes will be applied: chameleon migrate --dry-run
Review the generated SQL to ensure it matches your intentions.
Ensure Proper Mode
Migrations are blocked in readonly mode. Upgrade if needed: # Check current mode chameleon config get mode # If readonly, upgrade to standard chameleon config set mode=standard 🔐 Enter mode password: ****
See Mode Management for details.
Apply Migration
Execute the migration: chameleon migrate --apply
Output: 🔍 Verifying schema integrity... ✓ Current: v001 (3f2a8b9c...) ✓ No tampering detected 📦 Registering new schema version... ✓ Registered as v002 (hash: 7d4e1c2a...) ✓ Parent: v001 📋 Applying migration... ✓ ALTER TABLE users ADD COLUMN age INTEGER ✅ Migration applied successfully ✅ Schema v002 locked in vault
Verify Integrity
Confirm the migration was recorded correctly: Output: 🔍 Verifying Schema Vault integrity... ✓ v001: hash verified ✓ v002: hash verified ✅ All versions verified
Schema Vault Integration Every migration creates an immutable version in the vault:
Vault Structure .chameleon/vault/ ├── manifest.json # Current version + history ├── integrity.log # Append-only audit trail ├── versions/ │ ├── v001.json # Immutable snapshot │ └── v002.json └── hashes/ ├── v001.hash # SHA256 verification └── v002.hash
Version History View all schema versions:
Output: 📖 Schema Version History v002 (current) ✓ ├─ Hash: 7d4e1c2a... ├─ Date: 2026-02-20 15:45:00 ├─ Author: dperalta ├─ Changes: Added age field to User └─ Parent: v001 v001 ├─ Hash: 3f2a8b9c... ├─ Date: 2026-02-20 10:30:00 ├─ Author: dperalta ├─ Changes: Initial schema └─ Parent: none
Audit Trail View the complete integrity log:
cat .chameleon/vault/integrity.log
Migration Recovery If a migration fails midway, ChameleonDB can retry automatically:
chameleon migrate --apply
Output: ⚠️ Incomplete migration detected (v002) 🔄 Attempting recovery... ✅ Migration completed successfully
Environment Variables Set your database connection string:
export DATABASE_URL = "postgresql://user:password@localhost:5432/mydb"
Alternatively, use a .env file:
DATABASE_URL = postgresql://user:password@localhost:5432/mydb
Integrity Verification Automatic Verification Every chameleon migrate command automatically:
Verifies all schema hashes
Detects tampering
Aborts if integrity violation detected
Example (tampered vault): ❌ INTEGRITY VIOLATION DETECTED • v001.json: hash mismatch 🚨 Schema vault has been modified! ❌ Migration aborted for safety
Manual Verification Verify vault integrity anytime:
Common Issues ”readonly mode: schema modifications blocked” Solution: Upgrade mode to standard or higher:chameleon config auth set-password # First time only chameleon config set mode=standard
“DATABASE_URL not set” Solution: Set environment variable:export DATABASE_URL = "postgresql://user:pass@host:5432/db"
“integrity violation detected” Solution: Someone modified vault files. Check audit log:cat .chameleon/vault/integrity.log
If changes were unauthorized, restore from backup.
”vault not initialized” Solution: Run init first:Best Practices
Preview SQL before applying to catch unexpected changes: chameleon migrate --dry-run
Use readonly mode in production
Lock schema changes in production environments: chameleon config set mode=readonly
Review version history regularly
Audit schema changes periodically:
Backup vault before major changes
Create snapshots before risky operations: cp -r .chameleon/vault .chameleon/vault.backup
Keep connection strings out of version control: # .env (add to .gitignore) DATABASE_URL = postgresql://...
Next Steps
Introspection Generate schema from existing databases
Mode Management Control schema change permissions
Debugging Troubleshoot migrations and queries
Architecture Understand the Schema Vault system