> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chameleondb.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get started with ChameleonDB in 5 minutes

# 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](/installation) for detailed instructions on Linux, macOS, and Windows.

Quick install:

```bash theme={null}
# Linux and macOS
curl -sSL https://chameleondb.dev/install | sh
```

Verify installation:

```bash theme={null}
chameleon --version
# Output: chameleon v1.0-alpha
```

## Your First ChameleonDB Project

<Steps>
  <Step title="Initialize Project">
    Create a new directory and initialize ChameleonDB:

    ```bash theme={null}
    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'
    ```
  </Step>

  <Step title="Define Your Schema">
    Edit `schema.cham` to define your data model:

    ```go schema.cham theme={null}
    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:**

    ```bash theme={null}
    chameleon validate
    ```

    **Output:**

    ```
    ✅ Schema validated successfully
       Entities: 2 (User, Post)
       Relations: 2 (users.posts, posts.author)
    ```
  </Step>

  <Step title="Configure Database Connection">
    Set your PostgreSQL connection string:

    ```bash theme={null}
    export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
    ```

    <Note>
      Replace `user`, `password`, and `mydb` with your actual PostgreSQL credentials.
    </Note>
  </Step>

  <Step title="Run Migration">
    Apply your schema to the database:

    ```bash theme={null}
    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
    ```

    <Tip>
      Use `--dry-run` flag to preview SQL without applying: `chameleon migrate --dry-run`
    </Tip>
  </Step>

  <Step title="Use in Your Application">
    Initialize a Go module and add ChameleonDB:

    ```bash theme={null}
    go mod init my-app
    go get github.com/chameleon-db/chameleondb/chameleon
    ```

    Create `main.go`:

    ```go main.go theme={null}
    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:**

    ```bash theme={null}
    go run main.go
    ```

    **Output:**

    ```
    User created: 550e8400-e29b-41d4-a716-446655440000
    User: Ana Garcia <ana@mail.com>
    ```
  </Step>
</Steps>

## Query with Relations

ChameleonDB makes it easy to query related data:

```go theme={null}
// 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"])
        }
    }
}
```

<Note>
  Using `Include()` prevents N+1 query problems by eagerly loading related data. ChameleonDB's IdentityMap automatically deduplicates objects in memory.
</Note>

## Debug Mode

See the generated SQL for any query:

```go theme={null}
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:

<CodeGroup>
  ```bash View version history theme={null}
  chameleon journal schema
  ```

  ```bash Check status theme={null}
  chameleon status
  ```

  ```bash Verify integrity theme={null}
  chameleon verify
  ```

  ```bash View specific version theme={null}
  chameleon journal schema v001
  ```
</CodeGroup>

### Example: View Version History

```bash theme={null}
$ 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:

```bash theme={null}
# 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
```

<Warning>
  In `readonly` mode (the default), schema modifications are blocked. Upgrade to `standard` mode for development.
</Warning>

## Common Issues

<AccordionGroup>
  <Accordion title="vault not initialized">
    **Solution:** Run `chameleon init` in your project directory.

    ```bash theme={null}
    chameleon init
    ```
  </Accordion>

  <Accordion title="readonly mode: blocked">
    **Solution:** Upgrade to standard mode.

    ```bash theme={null}
    chameleon config auth set-password
    chameleon config set mode=standard
    ```
  </Accordion>

  <Accordion title="integrity violation">
    **Solution:** Check what changed and view the audit log.

    ```bash theme={null}
    chameleon verify
    cat .chameleon/vault/integrity.log
    ```
  </Accordion>

  <Accordion title="DATABASE_URL not set">
    **Solution:** Set the environment variable.

    ```bash theme={null}
    export DATABASE_URL="postgresql://user:pass@host:5432/db"
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation Guide" icon="download" href="/installation">
    Detailed installation for Linux, macOS, and Windows
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Complete guide to all CLI commands
  </Card>

  <Card title="Query API" icon="code" href="/api/engine">
    Type-safe query and mutation reference
  </Card>

  <Card title="Examples" icon="flask" href="https://github.com/chameleon-db/chameleon-examples">
    Real-world example applications
  </Card>
</CardGroup>

## 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](https://chameleondb.dev/docs)
* **GitHub Issues**: [https://github.com/chameleon-db/chameleondb/issues](https://github.com/chameleon-db/chameleondb/issues)
* **Discord**: [https://chameleondb.dev/discord](https://chameleondb.dev/discord)