Skip to main content

​
Quick Start Guide

Get started with ChameleonDB in 5 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Go 1.21+ installed
  • PostgreSQL 14+ running
  • Terminal access (bash, zsh, or PowerShell)

​
Installation

See the Installation Guide for detailed instructions on Linux, macOS, and Windows. Quick install: 
# Linux and macOS
curl -sSL https://chameleondb.dev/install | sh
Verify installation: 
chameleon --version
# Output: chameleon v1.0-alpha

​
Your First ChameleonDB Project

1

Initialize Project

Create a new directory and initialize ChameleonDB:
mkdir my-app
cd my-app
chameleon init
What happens:
  • Creates .chameleon/ directory
  • Initializes Schema Vault
  • Creates default schema.cham
  • Sets mode to readonly
Output:
✅ Created .chameleon/ directory
✅ Schema Vault initialized
✅ Created schema.cham
ℹ️  Paranoid Mode: readonly
💡 Tip: Set mode password with 'chameleon config auth set-password'
2

Define Your Schema

Edit schema.cham to define your data model:
schema.cham
entity User {
    id: uuid primary,
    email: string unique,
    name: string,
    created_at: timestamp default now(),
    posts: [Post] via author_id,
}

entity Post {
    id: uuid primary,
    title: string,
    content: string,
    published: bool default false,
    created_at: timestamp default now(),
    author_id: uuid,
    author: User,
}
Validate your schema:
chameleon validate
Output:
✅ Schema validated successfully
   Entities: 2 (User, Post)
   Relations: 2 (users.posts, posts.author)
3

Configure Database Connection

Set your PostgreSQL connection string:
export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
Replace user, password, and mydb with your actual PostgreSQL credentials.
4

Run Migration

Apply your schema to the database:
chameleon migrate --apply
Output:
📦 Initializing Schema Vault...
   ✓ Created .chameleon/vault/
   ✓ Registered schema as v001
   ✓ Hash: 3f2a8b9c...

📋 Migration Preview:
─────────────────────────────────────────────────
CREATE TABLE users (
    id UUID PRIMARY KEY,
    email VARCHAR UNIQUE NOT NULL,
    name VARCHAR NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE posts (
    id UUID PRIMARY KEY,
    title VARCHAR NOT NULL,
    content TEXT,
    published BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    author_id UUID REFERENCES users(id)
);
─────────────────────────────────────────────────

✅ Migration applied successfully
✅ Schema v001 locked in vault
Use --dry-run flag to preview SQL without applying: chameleon migrate --dry-run
5

Use in Your Application

Initialize a Go module and add ChameleonDB:
go mod init my-app
go get github.com/chameleon-db/chameleondb/chameleon
Create main.go:
main.go
package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/chameleon-db/chameleondb/chameleon/pkg/engine"
    "github.com/google/uuid"
)

func main() {
    ctx := context.Background()
    
    // Connect (loads schema from vault automatically)
    eng, err := engine.NewEngine()
    if err != nil {
        log.Fatal(err)
    }
    defer eng.Close()
    
    // Insert user
    result, err := eng.Insert("User").
        Set("id", uuid.New().String()).
        Set("email", "ana@mail.com").
        Set("name", "Ana Garcia").
        Execute(ctx)
    
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("User created: %v\n", result.ID)
    
    // Query users
    users, err := eng.Query("User").
        Filter("email", "eq", "ana@mail.com").
        Execute(ctx)
    
    if err != nil {
        log.Fatal(err)
    }
    
    for _, user := range users.Rows {
        fmt.Printf("User: %s <%s>\n", user["name"], user["email"])
    }
}
Run your application:
go run main.go
Output:
User created: 550e8400-e29b-41d4-a716-446655440000
User: Ana Garcia <ana@mail.com>

​
Query with Relations

ChameleonDB makes it easy to query related data: 
// Query users with their posts (eager loading)
result, err := eng.Query("User").
    Select("id", "name", "email").
    Include("posts").
    Execute(ctx)

if err != nil {
    log.Fatal(err)
}

for _, user := range result.Rows {
    fmt.Printf("User: %s\n", user["name"])
    
    if posts, ok := result.Relations["posts"]; ok {
        fmt.Printf("  Posts: %d\n", len(posts))
        for _, post := range posts {
            fmt.Printf("  - %s\n", post["title"])
        }
    }
}
Using Include() prevents N+1 query problems by eagerly loading related data. ChameleonDB’s IdentityMap automatically deduplicates objects in memory.

​
Debug Mode

See the generated SQL for any query: 
result, err := eng.Query("User").
    Filter("email", "like", "ana").
    Debug().  // ← Shows SQL
    Execute(ctx)
Output: 
[SQL] Query User
SELECT * FROM users WHERE email LIKE '%ana%'

[TRACE] Query on User: 2.3ms, 1 rows

​
Schema Vault Commands

ChameleonDB tracks every schema change in the Schema Vault: 
chameleon journal schema

​
Example: View Version History

$ chameleon journal schema

📖 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

​
Integrity Modes

ChameleonDB uses integrity modes to control who can modify schemas: 
# Check current mode
chameleon status

# Set password for mode upgrades (recommended)
chameleon config auth set-password
# Enter new password: ********
# ✅ Mode password configured

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

# Downgrade (no password required)
chameleon config set mode=readonly
# ✅ Mode downgraded to readonly
In readonly mode (the default), schema modifications are blocked. Upgrade to standard mode for development.

​
Common Issues

Solution: Run chameleon init in your project directory.
chameleon init
Solution: Upgrade to standard mode.
chameleon config auth set-password
chameleon config set mode=standard
Solution: Check what changed and view the audit log.
chameleon verify
cat .chameleon/vault/integrity.log
Solution: Set the environment variable.
export DATABASE_URL="postgresql://user:pass@host:5432/db"

​
Next Steps

Installation Guide

Detailed installation for Linux, macOS, and Windows

CLI Reference

Complete guide to all CLI commands

Query API

Type-safe query and mutation reference

Examples

Real-world example applications

​
What You’ve Learned

  • ✅ How to initialize ChameleonDB projects
  • ✅ How to define schemas in .cham files
  • ✅ How to run migrations with the Schema Vault
  • ✅ How to query data with the Go SDK
  • ✅ How to use Debug mode to see SQL
  • ✅ How to manage integrity modes

​
Getting Help