​

Welcome to ChameleonDB

​

The Problem

• Schema drift happens silently over time
• Migration failures leave databases in unknown states
• Authority for schema changes is implicit, not enforced
• Audit trails are external, incomplete, or missing
• Rollback is manual and error-prone

​

The ChameleonDB Solution

​

Quick Example

entity User {
    id: uuid primary,
    email: string unique,
    name: string,
    posts: [Post] via author_id,
}

entity Post {
    id: uuid primary,
    title: string,
    content: string,
    published: bool,
    author_id: uuid,
    author: User,
}

chameleon init                  # Creates .chameleon/vault/
chameleon migrate --apply       # Registers v001, applies migration

.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

​

What You Get

• Immutable schema versions — Tamper-proof with SHA256 hashing
• Integrity verification — Automatic checks before every operation
• Explicit governance — Ring-based modes (readonly/standard/privileged/emergency)
• Complete audit trail — Append-only log, never deleted
• Zero-config vault — Auto-initializes on first migrate
• Password-protected upgrades — Mode escalation requires auth
• Migration recovery — Retry failed migrations automatically

​

Get Started

​

Key Features

​

Schema Vault (v1.0)

# Every migration creates a new version
$ chameleon migrate --apply

📦 Registering new schema version...
   ✓ Registered as v002 (hash: 7d4e1c2a...)
   ✓ Parent: v001

✅ Migration applied successfully
✅ Schema v002 locked in vault

​

Integrity Modes (v1.0)

# Default mode: readonly (schema locked)
$ chameleon migrate --apply
❌ readonly mode: schema modifications blocked

# Upgrade to allow schema changes
$ chameleon config set mode=standard
🔐 Enter mode password: ****
✅ Mode upgraded to standard

# Now migrations are allowed
$ chameleon migrate --apply
✅ Migration applied successfully

​

Query System (v1.0)

// Query only the fields you need
users := db.Query("User").
    Select("id", "name", "email").  // Partial selection
    Filter("age", "gt", 25).
    Include("posts").                // Eager load (no N+1)
    Execute(ctx)

// Debug mode (see generated SQL)
users := db.Query("User").
    Select("id", "name").
    Filter("email", "like", "ana").
    Debug().
    Execute(ctx)

// Output:
// [SQL] Query User
// SELECT id, name FROM users WHERE email LIKE '%ana%'
// [TRACE] Query on User: 2.3ms, 3 rows

​

IdentityMap (v1.0)

// Without IdentityMap (wasteful)
// If User has 100 posts, User object is duplicated 100 times in memory

// With IdentityMap (efficient)
result := db.Query("User").
    Include("posts").
    Execute(ctx)

// User object appears only once
// All 100 posts reference the same User instance
// Memory savings: ~99% for large result sets

​

Why ChameleonDB?

​

vs Traditional Databases

​

Key Differentiators

1. Schema as First-Class Artifact: Versioned, immutable, hash-verified
2. Runtime Governance: Integrity Modes enforced by the system
3. Zero-Config Vault: Auto-initializes, works out of the box
4. Complete Audit Trail: Append-only, never deleted
5. Explicit Authority: Mode upgrades require password

​

Current Status

​

Available Now (v1.0-alpha)

• ✅ Schema Vault (versioned, hash-verified)
• ✅ Integrity Modes (readonly/standard/privileged/emergency)
• ✅ Password-protected mode upgrades
• ✅ Automatic integrity verification
• ✅ Append-only audit trail
• ✅ Migration recovery (retry failed migrations)

• ✅ Schema parser and type checker
• ✅ Query builder with filters
• ✅ Field projection (.Select())
• ✅ Eager loading (.Include())
• ✅ Nested includes
• ✅ IdentityMap (object deduplication)
• ✅ Debug mode (.Debug())

• ✅ CLI tools (init, migrate, verify, status)
• ✅ Rich error messages with suggestions
• ✅ PostgreSQL migration generator
• ✅ Database introspection (PostgreSQL)
• ✅ 300+ tests (unit + integration)

​

Coming Soon

• v1.1 (March 2026): Schema Vault rollback, Transaction support, Batch operations
• v1.2+ (Q2 2026): Additional backends (MySQL, DuckDB), Code generation, Multi-language support
• v1.5+ (2027): ML-based query optimization, Visual schema editor, Distributed vault

​

Community & Support

• Documentation: https://chameleondb.dev/docs
• Examples: https://github.com/chameleon-db/chameleon-examples
• Discord: https://chameleondb.dev/discord
• GitHub Issues: https://github.com/chameleon-db/chameleondb/issues