> ## 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. # Migration Workflow > Complete guide to ChameleonDB's migration system with Schema Vault integration 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: ```bash theme={null} chameleon status ``` **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: ```bash theme={null} chameleon migrate ``` 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: ```bash theme={null} 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: ```bash theme={null} 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 Edit your `schema.cham` file to add, remove, or modify entities and fields: ```go theme={null} entity User { id: uuid primary, email: string unique, name: string, age: int, // ← New field } ``` Ensure your schema is syntactically correct: ```bash theme={null} chameleon validate ``` **Output:** ``` ✅ Schema validated successfully Entities: 1 (User) Fields: 4 ``` Check what changes will be applied: ```bash theme={null} chameleon migrate --dry-run ``` Review the generated SQL to ensure it matches your intentions. Migrations are blocked in readonly mode. Upgrade if needed: ```bash theme={null} # Check current mode chameleon config get mode # If readonly, upgrade to standard chameleon config set mode=standard 🔐 Enter mode password: **** ``` See [Mode Management](/guides/mode-management) for details. Execute the migration: ```bash theme={null} 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 ``` Confirm the migration was recorded correctly: ```bash theme={null} chameleon verify ``` **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: ```bash theme={null} chameleon journal schema ``` **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: ```bash theme={null} cat .chameleon/vault/integrity.log ``` ## Migration Recovery If a migration fails midway, ChameleonDB can retry automatically: ```bash theme={null} chameleon migrate --apply ``` **Output:** ``` ⚠️ Incomplete migration detected (v002) 🔄 Attempting recovery... ✅ Migration completed successfully ``` ## Environment Variables Set your database connection string: ```bash theme={null} export DATABASE_URL="postgresql://user:password@localhost:5432/mydb" ``` Alternatively, use a `.env` file: ```bash .env theme={null} DATABASE_URL=postgresql://user:password@localhost:5432/mydb ``` ## Integrity Verification ### Automatic Verification Every `chameleon migrate` command automatically: 1. Verifies all schema hashes 2. Detects tampering 3. 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: ```bash theme={null} chameleon verify ``` ## Common Issues ### "readonly mode: schema modifications blocked" **Solution:** Upgrade mode to standard or higher: ```bash theme={null} chameleon config auth set-password # First time only chameleon config set mode=standard ``` ### "DATABASE\_URL not set" **Solution:** Set environment variable: ```bash theme={null} export DATABASE_URL="postgresql://user:pass@host:5432/db" ``` ### "integrity violation detected" **Solution:** Someone modified vault files. Check audit log: ```bash theme={null} cat .chameleon/vault/integrity.log ``` If changes were unauthorized, restore from backup. ### "vault not initialized" **Solution:** Run init first: ```bash theme={null} chameleon init ``` ## Best Practices Preview SQL before applying to catch unexpected changes: ```bash theme={null} chameleon migrate --dry-run ``` Lock schema changes in production environments: ```bash theme={null} chameleon config set mode=readonly ``` Audit schema changes periodically: ```bash theme={null} chameleon journal schema ``` Create snapshots before risky operations: ```bash theme={null} cp -r .chameleon/vault .chameleon/vault.backup ``` Keep connection strings out of version control: ```bash theme={null} # .env (add to .gitignore) DATABASE_URL=postgresql://... ``` ## Next Steps Generate schema from existing databases Control schema change permissions Troubleshoot migrations and queries Understand the Schema Vault system