Database Introspection

The chameleon introspect command inspects an existing database schema and generates a ChameleonDB schema file (.cham). This is essential for:

Bootstrapping from legacy databases
Validating table discovery
Generating baseline schemas for migration workflows

Currently, introspection only supports PostgreSQL. Support for MySQL and other databases is planned for v1.2+.

Command Syntax

chameleon introspect <database-url> [--output <file>] [--force]

Parameters

Parameter	Short	Description	Default
`<database-url>`	-	Database connection string (required)	-
`--output`	`-o`	Output file path	`schema.cham`
`--force`	`-f`	Bypass overwrite safety checks	`false`

Connection String Formats

ChameleonDB supports multiple connection string formats for flexibility:

1. Direct URL

Provide the full connection string directly:

chameleon introspect postgresql://user:pass@localhost:5432/mydb

2. Shell-style Environment Variable (`$VAR`)

Reference an environment variable using shell syntax:

export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
chameleon introspect $DATABASE_URL

3. Braced Environment Variable (`${VAR}`)

Use braced syntax for clarity:

chameleon introspect ${DATABASE_URL}

4. Explicit Environment Reference (`env:VAR`)

Use explicit env: prefix:

chameleon introspect env:DATABASE_URL

If the referenced environment variable is missing or empty, the command will fail with an explicit error message.

Basic Introspection Workflow

Set Your Connection String

Export your database URL as an environment variable:

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

Ensure Proper Mode

Introspection requires standard mode or higher (blocked in readonly):

# Check current mode
chameleon config get mode

# If readonly, upgrade
chameleon config auth set-password  # First time only
chameleon config set mode=standard

See Mode Management for details.

Run Introspection

Generate the schema file:

chameleon introspect $DATABASE_URL -o schema.cham

Output:

🔍 Introspecting database...
   ✓ Connected to PostgreSQL
   ✓ Found 3 tables
   ✓ Found 12 columns
   ✓ Found 2 foreign keys

📝 Generated schema.cham
✅ Introspection complete

Review Generated Schema

Open the generated file and review:

cat schema.cham

Example output:

entity users {
    id: uuid primary,
    email: string unique,
    name: string,
    created_at: timestamp,
}

entity posts {
    id: uuid primary,
    title: string,
    content: string,
    author_id: uuid,
    author: users,
}

Validate and Customize

Validate the schema and make manual adjustments:

chameleon validate

Common customizations:

Rename entities to match your conventions
Add missing relations
Adjust field types
Add default values

Mode Restrictions

Introspection behavior depends on your current integrity mode:

Mode	Introspect Behavior
`readonly`	❌ Blocked
`standard`	✅ Allowed
`privileged`	✅ Allowed
`emergency`	✅ Allowed

Upgrading from readonly

Since mode upgrades require 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
🔐 Enter mode password: ****
✅ Mode upgraded to standard

# Now introspect
chameleon introspect $DATABASE_URL

Mode upgrade requires password (e.g., readonly → standard)Mode downgrade does NOT require password (e.g., standard → readonly)

Output File Safety Checks

Without --force, introspection applies safety protections:

1. Directory Check

Validates that the output path is not a directory:

chameleon introspect $DATABASE_URL -o ./schemas/

Output:

❌ Error: output path is a directory
💡 Specify a file path: -o ./schemas/schema.cham

2. Template Detection

Detects default template schemas created by chameleon init:

chameleon introspect $DATABASE_URL -o schema.cham

If schema.cham is an unmodified template:

✅ Overwriting default template schema.cham

3. Modified Schema Detection

Detects working schemas and prompts for safety:

chameleon introspect $DATABASE_URL -o schema.cham

Output:

⚠️  schema.cham already exists and has been modified

Options:
  1. Backup existing file and continue
  2. Specify a different output file
  3. Abort

Choice [1-3]:

4. Force Overwrite

Bypass all safety checks:

chameleon introspect $DATABASE_URL -o schema.cham --force

Use --force carefully — it will overwrite existing files without confirmation.

Complete Examples

Baseline Introspection (Railway-style)

Introspect a Railway PostgreSQL instance:

# Set connection string
export DATABASE_URL="postgresql://postgres:[email protected]:5432/railway"

# Introspect to separate file
chameleon introspect $DATABASE_URL -o schema.introspected.cham

# Review
cat schema.introspected.cham

Explicit Environment Resolver

Use explicit env: syntax:

chameleon introspect env:DATABASE_URL --output schema.cham

Overwrite Existing Schema Intentionally

Force overwrite without prompts:

chameleon introspect $DATABASE_URL --output schema.cham --force

Introspect Production Database

# Export production URL
export PROD_DATABASE_URL="postgresql://user:[email protected]:5432/proddb"

# Introspect to versioned file
chameleon introspect $PROD_DATABASE_URL -o schema.prod.$(date +%Y%m%d).cham

# Review generated schema
cat schema.prod.20260220.cham

Post-Introspection Workflow

1. Validate Generated Schema

chameleon validate

Expected output:

✅ Schema validated successfully
   Entities: 5
   Relations: 8

2. Review Relations

Introspection discovers foreign keys but may need manual review:

// Auto-discovered relation
entity posts {
    author_id: uuid,
    author: users,  // ← Verify this is correct
}

// You might want to add the reverse relation:
entity users {
    posts: [posts] via author_id,
}

3. Customize Naming

Rename entities to match your conventions:

// Before (table names)
entity user_accounts { ... }

// After (PascalCase)
entity UserAccount { ... }

4. Apply Migration

Once satisfied, apply to initialize vault:

chameleon migrate --apply

Common Issues

”readonly mode: introspection blocked”

Solution: Upgrade mode:

chameleon config auth set-password
chameleon config set mode=standard

“DATABASE_URL environment variable not set”

Solution: Export the variable:

export DATABASE_URL="postgresql://..."

“output path is a directory”

Solution: Specify a file path:

chameleon introspect $DATABASE_URL -o schema.cham

“connection refused”

Solution: Verify database is running and accessible:

psql $DATABASE_URL -c "SELECT 1;"

Operational Notes

Introspection is read-only

Introspection only reads database metadata. It never modifies your database.

Review generated relations

Foreign keys are auto-discovered, but you should manually verify:

Relation names make sense
Reverse relations are added where needed
Cardinality is correct (one-to-many vs many-to-many)

Naming conventions

Introspection uses database table/column names directly. You may want to:

Convert snake_case to PascalCase for entities
Use singular names (e.g., User instead of users)

Follow up with validation

Always validate after introspection:

chameleon validate

Use version control

Track generated schemas in Git to review changes:

git add schema.cham
git commit -m "Add introspected schema from production"

Best Practices

Use separate files for introspection
```
chameleon introspect $DATABASE_URL -o schema.introspected.cham
```
Compare with your working schema before merging.

Version introspected schemas

chameleon introspect $DATABASE_URL -o schema.$(date +%Y%m%d).cham

Always validate after introspection
```
chameleon validate
```
Review before applying
```
chameleon migrate --dry-run
```

Next Steps

Migration Workflow

Apply introspected schema to database

Schema Language

Learn schema syntax and features

Mode Management

Understand integrity modes

Debugging

Troubleshoot introspection issues

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

​Command Syntax

​Parameters

​Connection String Formats

​1. Direct URL

​2. Shell-style Environment Variable ($VAR)

​3. Braced Environment Variable (${VAR})

​4. Explicit Environment Reference (env:VAR)

​Basic Introspection Workflow

​Mode Restrictions

​Upgrading from readonly

​Output File Safety Checks

​1. Directory Check

​2. Template Detection

​3. Modified Schema Detection

​4. Force Overwrite

​Complete Examples

​Baseline Introspection (Railway-style)

​Explicit Environment Resolver

​Overwrite Existing Schema Intentionally

​Introspect Production Database

​Post-Introspection Workflow

​1. Validate Generated Schema

​2. Review Relations

​3. Customize Naming

​4. Apply Migration

​Common Issues

​”readonly mode: introspection blocked”

​“DATABASE_URL environment variable not set”

​“output path is a directory”

​“connection refused”

​Operational Notes

​Best Practices

​Next Steps

Migration Workflow

Schema Language

Mode Management

Debugging

Build docs developers (and LLMs) love

Command Syntax

Parameters

Connection String Formats

1. Direct URL

2. Shell-style Environment Variable (`$VAR`)

3. Braced Environment Variable (`${VAR}`)

4. Explicit Environment Reference (`env:VAR`)

Basic Introspection Workflow

Mode Restrictions

Upgrading from readonly

Output File Safety Checks

1. Directory Check

2. Template Detection

3. Modified Schema Detection

4. Force Overwrite

Complete Examples

Baseline Introspection (Railway-style)

Explicit Environment Resolver

Overwrite Existing Schema Intentionally

Introspect Production Database

Post-Introspection Workflow

1. Validate Generated Schema

2. Review Relations

3. Customize Naming

4. Apply Migration

Common Issues

”readonly mode: introspection blocked”

“DATABASE_URL environment variable not set”

“output path is a directory”

“connection refused”

Operational Notes

Best Practices

Next Steps