Migration Workflow

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:

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:

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:

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:

chameleon validate

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:

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:

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:

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:

.env

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:

chameleon verify

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:

chameleon init

Best Practices

Always run dry-run first

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:

chameleon journal schema

Backup vault before major changes

Create snapshots before risky operations:

cp -r .chameleon/vault .chameleon/vault.backup

Set DATABASE_URL in .env

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

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

Overview

Migration Commands

Check Migration Status

Preview Changes

Dry Run (View Generated SQL)

Apply Migration

Complete Migration Workflow

Schema Vault Integration

Vault Structure

Version History

Audit Trail

Migration Recovery

Environment Variables

Integrity Verification

Automatic Verification

Manual Verification

Common Issues

”readonly mode: schema modifications blocked”

“DATABASE_URL not set”

“integrity violation detected”

”vault not initialized”

Best Practices

Next Steps

Introspection

Mode Management

Debugging

Architecture

​Overview

​Migration Commands

​Check Migration Status

​Preview Changes

​Dry Run (View Generated SQL)

​Apply Migration

​Complete Migration Workflow

​Schema Vault Integration

​Vault Structure

​Version History

​Audit Trail

​Migration Recovery

​Environment Variables

​Integrity Verification

​Automatic Verification

​Manual Verification

​Common Issues

​”readonly mode: schema modifications blocked”

​“DATABASE_URL not set”

​“integrity violation detected”

​”vault not initialized”

​Best Practices

​Next Steps

Introspection

Mode Management

Debugging

Architecture

Overview

Migration Commands

Check Migration Status

Preview Changes

Dry Run (View Generated SQL)

Apply Migration

Complete Migration Workflow

Schema Vault Integration

Vault Structure

Version History

Audit Trail

Migration Recovery

Environment Variables

Integrity Verification

Automatic Verification

Manual Verification

Common Issues

”readonly mode: schema modifications blocked”

“DATABASE_URL not set”

“integrity violation detected”

”vault not initialized”

Best Practices

Next Steps