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

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'

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)

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.

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

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

chameleon status

chameleon verify

chameleon journal schema v001

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

vault not initialized

Solution: Run chameleon init in your project directory.

chameleon init

readonly mode: blocked

Solution: Upgrade to standard mode.

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

integrity violation

Solution: Check what changed and view the audit log.

chameleon verify
cat .chameleon/vault/integrity.log

DATABASE_URL not set

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

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

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

Quick Start

Quick Start Guide

Prerequisites

Installation

Your First ChameleonDB Project

Query with Relations

Debug Mode

Schema Vault Commands

Example: View Version History

Integrity Modes

Common Issues

Next Steps

Installation Guide

CLI Reference

Query API

Examples

What You’ve Learned

Getting Help

​Quick Start Guide

​Prerequisites

​Installation

​Your First ChameleonDB Project

​Query with Relations

​Debug Mode

​Schema Vault Commands

​Example: View Version History

​Integrity Modes

​Common Issues

​Next Steps

Installation Guide

CLI Reference

Query API

Examples

​What You’ve Learned

​Getting Help

Quick Start Guide

Prerequisites

Installation

Your First ChameleonDB Project

Query with Relations

Debug Mode

Schema Vault Commands

Example: View Version History

Integrity Modes

Common Issues

Next Steps

What You’ve Learned

Getting Help