chameleon migrate

Synopsis

chameleon migrate [flags]

Generate, validate, or apply database migrations from schema files.

Description

The migrate command:

Verifies Schema Vault integrity - Checks all version hashes
Checks paranoid mode - Ensures schema changes are allowed
Loads and merges schemas - Combines all .cham files from configured paths
Detects changes - Compares merged schema with current vault version
Generates migration SQL - Creates DDL statements
Registers new version - Creates immutable snapshot in vault (if --apply)
Applies migration - Executes SQL against database (if --apply)
Updates state - Records migration in manifest and journal

By default, runs in check mode (shows pending migrations without applying).

Flags

boolean

default:"true"

Check for pending migrations without applying (default behavior)

chameleon migrate --check
chameleon migrate  # same as --check

boolean

default:"false"

Preview migration SQL without applying to database

chameleon migrate --dry-run

Shows:

Schema changes summary
Generated SQL
Does NOT register version or apply migration

boolean

default:"false"

Apply migration to database

chameleon migrate --apply

Registers new schema version in vault
Executes migration SQL
Updates state and journal
Creates backup (if enabled in config)

Environment Variables

string

required

PostgreSQL connection string

export DATABASE_URL="postgresql://user:password@localhost:5432/dbname"

string

Used as author name for schema versions. Defaults to “unknown” if not set.

Examples

Check for Pending Migrations

chameleon migrate

Output (no changes):

ℹ Loading configuration...
✓ Configuration loaded from .chameleon.yml
ℹ Verifying schema integrity...
✓ Current version: v001 (3f2a8b9c...)
ℹ Paranoid Mode active: standard
ℹ Loading schemas from: [./schemas]
✓ Found 1 schema file(s): [example.cham]
✓ Schema loaded and validated
ℹ No schema changes detected

✓ Schema is up to date

Output (changes detected):

ℹ Schema changes detected: Added age field to User
ℹ Generating migration SQL...
✓ Migration SQL generated

─────────────────────────────────────────────────
Migration SQL:
─────────────────────────────────────────────────
ALTER TABLE users ADD COLUMN age INTEGER;
─────────────────────────────────────────────────

ℹ Dry-run mode. Use --apply to execute migration.

Preview Migration SQL

chameleon migrate --dry-run

Output:

✓ Configuration loaded from .chameleon.yml
✓ Current version: v001 (3f2a8b9c...)
ℹ Paranoid Mode active: standard
✓ Found 2 schema file(s): [users.cham posts.cham]
✓ Schema loaded and validated
ℹ Schema changes detected: Added Post entity
ℹ Generating migration SQL...
✓ Migration SQL generated

─────────────────────────────────────────────────
Migration SQL:
─────────────────────────────────────────────────
CREATE TABLE posts (
    id UUID PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    content TEXT,
    author_id UUID REFERENCES users(id),
    created_at TIMESTAMP DEFAULT NOW()
);
─────────────────────────────────────────────────

ℹ Dry-run mode. Use --apply to execute migration.

Apply Migration

chameleon migrate --apply

Output:

ℹ Loading configuration...
✓ Configuration loaded from .chameleon.yml
ℹ Verifying schema integrity...
✓ Current version: v001 (3f2a8b9c...)
ℹ Paranoid Mode active: standard
ℹ Loading schemas from: [./schemas]
✓ Found 1 schema file(s): [users.cham]
✓ Schema loaded and validated
ℹ Schema changes detected: Added email index
ℹ Generating migration SQL...
✓ Migration SQL generated

─────────────────────────────────────────────────
Migration SQL:
─────────────────────────────────────────────────
CREATE INDEX idx_users_email ON users(email);
─────────────────────────────────────────────────

ℹ Registering new schema version...
✓ Registered as v002 (hash: 7d4e1c2a...)
ℹ Parent version: v001
ℹ Connecting to database...
✓ Connected to database
ℹ Applying migration...
✓ Migration applied successfully
ℹ Updating state...
✓ State updated

✓ Migration completed successfully!

Summary:
  Version:  v002
  Hash:     7d4e1c2a3b5f6e8d...
  Duration: 23ms
  Status:   applied

Before Migration

Schema Files

schemas/users.cham:

entity User {
    id: uuid primary,
    email: string unique,
    name: string,
}

Vault State

chameleon journal schema

Output:

📖 Schema Version History

v001 (current) ✓
├─ Hash: 3f2a8b9c...
├─ Date: 2026-03-03 10:30:00
├─ Author: dperalta
├─ Changes: Initial schema
└─ Parent: none

After Migration

Modified Schema

schemas/users.cham:

entity User {
    id: uuid primary,
    email: string unique,
    name: string,
    age: int,  // Added field
}

Run Migration

chameleon migrate --apply

Updated Vault State

chameleon journal schema

Output:

📖 Schema Version History

v002 (current) ✓
├─ Hash: 7d4e1c2a...
├─ Date: 2026-03-03 14:25:00
├─ Author: dperalta
├─ Changes: Added age field to User
└─ Parent: v001

v001
├─ Hash: 3f2a8b9c...
├─ Date: 2026-03-03 10:30:00
├─ Author: dperalta
├─ Changes: Initial schema
└─ Parent: none

Paranoid Mode Behavior

Readonly Mode (Default)

chameleon migrate --apply

Error:

❌ Read Only Paranoid Mode is active - schema modifications are blocked

ℹ To override (not recommended):
   1. Set mode password: chameleon config auth set-password
   2. Upgrade paranoid mode: chameleon config set mode=standard
   3. Fix integrity issues first

❌ readonly mode: schema locked

Standard Mode

# Upgrade mode first
chameleon config set mode=standard

# Now migrations work
chameleon migrate --apply
✓ Migration applied successfully

Integrity Verification

Integrity Check Passed

✓ Verifying schema integrity...
✓ Current version: v002 (7d4e1c2a...)
ℹ Paranoid Mode active: standard

Integrity Violation Detected

❌ INTEGRITY VIOLATION DETECTED

  • v001.json: hash mismatch (expected 3f2a8b9c..., got a1b2c3d4...)
  • v002.hash: file modified or corrupted

❌ Schema vault has been modified!
Recovery options:
   1. Run 'chameleon verify' for details
   2. Check .chameleon/vault/integrity.log
   3. Contact your DBA

❌ Migration aborted for safety

Error Handling

Connection Failure

❌ Failed to connect to database: connection refused
   
ℹ Check:
   - DATABASE_URL is set correctly
   - Database is running
   - Network connectivity

Schema Validation Error

❌ Schema validation failed

Error in users.cham:12
  12 │     email: strnig unique,
     │            ^^^^^^
     │            Unknown type 'strnig'

Help: Did you mean 'string'?

Migration Execution Error

❌ Migration failed
❌ failed to execute migration: ERROR: column "age" already exists

ℹ Migration marked as failed in state
ℹ Run 'chameleon journal errors' to view details

Migration Retry

If a migration fails, ChameleonDB tracks it:

# First attempt (fails)
chameleon migrate --apply
❌ Migration failed

# Fix the issue, then retry
chameleon migrate --apply
⚠ Schema unchanged, but latest version v002 is not applied to database
ℹ Retrying migration for v002...
✓ Migration applied successfully

Configuration

Migration behavior is controlled by .chameleon.yml:

schema:
  paths:
    - ./schemas          # Where to find .cham files
  merged_output: .chameleon/state/schema.merged.cham

features:
  backup_on_migrate: true  # Create backup before applying
  auto_migration: true
  audit_logging: true

Commands

Synopsis

Description

Flags

Environment Variables

Examples

Check for Pending Migrations

Preview Migration SQL

Apply Migration

Before Migration

Schema Files

Vault State

After Migration

Modified Schema

Run Migration

Updated Vault State

Paranoid Mode Behavior

Readonly Mode (Default)

Standard Mode

Integrity Verification

Integrity Check Passed

Integrity Violation Detected

Error Handling

Connection Failure

Schema Validation Error

Migration Execution Error

Migration Retry

Configuration

See Also

​Synopsis

​Description

​Flags

​Environment Variables

​Examples

​Check for Pending Migrations

​Preview Migration SQL

​Apply Migration

​Before Migration

​Schema Files

​Vault State

​After Migration

​Modified Schema

​Run Migration

​Updated Vault State

​Paranoid Mode Behavior

​Readonly Mode (Default)

​Standard Mode

​Integrity Verification

​Integrity Check Passed

​Integrity Violation Detected

​Error Handling

​Connection Failure

​Schema Validation Error

​Migration Execution Error

​Migration Retry

​Configuration

​See Also

Synopsis

Description

Flags

Environment Variables

Examples

Check for Pending Migrations

Preview Migration SQL

Apply Migration

Before Migration

Schema Files

Vault State

After Migration

Modified Schema

Run Migration

Updated Vault State

Paranoid Mode Behavior

Readonly Mode (Default)

Standard Mode

Integrity Verification

Integrity Check Passed

Integrity Violation Detected

Error Handling

Connection Failure

Schema Validation Error

Migration Execution Error

Migration Retry

Configuration

See Also