Schema Vault

The Schema Vault is ChameleonDB’s core feature for treating schemas as first-class, immutable artifacts with explicit integrity guarantees.

Overview

Unlike traditional databases that treat schema evolution as an auxiliary concern, ChameleonDB governs schemas at runtime through versioning, cryptographic integrity, and automatic verification.

The Schema Vault auto-initializes on first migrate with zero configuration required.

The Problem

Modern database systems enforce strong guarantees over data but treat schema evolution informally:

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 Solution

ChameleonDB’s Schema Vault provides: ✅ Immutable schema versions — Tamper-proof with SHA256 hashing
✅ Integrity verification — Automatic checks before every operation
✅ Complete audit trail — Append-only log, never deleted
✅ Zero-config vault — Auto-initializes on first migrate
✅ Lineage tracking — Parent version references

Vault Structure

The Schema Vault lives in the .chameleon/vault/ directory:

.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

manifest.json

Tracks the current version and complete version history:

{
  "current_version": "v002",
  "history": [
    {
      "version": "v001",
      "hash": "3f2a8b9c...",
      "date": "2026-02-20T10:30:00Z",
      "author": "dperalta",
      "parent": null
    },
    {
      "version": "v002",
      "hash": "7d4e1c2a...",
      "date": "2026-02-20T15:45:00Z",
      "author": "dperalta",
      "parent": "v001"
    }
  ]
}

versions/

Contains immutable schema snapshots. Once registered, these files are never modified. Example v001.json:

{
  "version": "v001",
  "entities": [
    {
      "name": "User",
      "fields": [
        {"name": "id", "type": "uuid", "primary": true},
        {"name": "email", "type": "string", "unique": true},
        {"name": "name", "type": "string"}
      ]
    }
  ]
}

hashes/

Stores SHA256 hashes for tamper detection. Each version has a corresponding .hash file.

integrity.log

Append-only audit trail recording all vault operations:

2026-02-20T10:30:00Z [REGISTER] v001 (hash: 3f2a8b9c...) by dperalta
2026-02-20T10:30:15Z [VERIFY]   v001 ✓ OK
2026-02-20T15:45:00Z [REGISTER] v002 (hash: 7d4e1c2a..., parent: v001) by dperalta
2026-02-20T15:45:10Z [VERIFY]   v002 ✓ OK

The integrity.log is never deleted. It provides complete forensics for compliance and debugging.

How It Works

1. Define Your Schema

Create a schema.cham file with versioned entities:

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,
}

2. Initialize the Vault

chameleon init                  # Creates .chameleon/vault/

The vault is created with readonly mode by default for security.

3. Apply Migration

chameleon migrate --apply       # Registers v001, applies migration

This automatically:

Computes SHA256 hash of the schema
Registers it as version v001
Saves snapshot to vault/versions/v001.json
Saves hash to vault/hashes/v001.hash
Updates manifest.json
Logs operation to integrity.log
Applies migration to database

4. Automatic Verification

Every operation verifies integrity:

$ chameleon migrate

🔍 Verifying schema integrity...
   ✓ Current: v001 (3f2a8b9c...)
   ✓ No tampering detected

5. Tamper Detection

If someone modifies vault files:

❌ INTEGRITY VIOLATION DETECTED
   • v001.json: hash mismatch
   🚨 Schema vault has been modified!
   ❌ Migration aborted for safety

Integrity violations always abort operations. This is a critical safety feature.

Version History

View the complete 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

Workflow

The complete vault registration workflow:

User modifies schema.cham
chameleon migrate detects changes
Compute SHA256 hash
Register as v002 (parent: v001)
Save snapshot to vault/versions/v002.json
Save hash to vault/hashes/v002.hash
Update manifest.json
Log to integrity.log
Apply migration to database

Security Model

The vault uses multiple layers of security:

OS Permissions - File access control (0700)
Hash Integrity - SHA256 tamper detection
Integrity Modes - Runtime access control (see Integrity Modes)
Vault Enforcement - No schema bypass in v1.0+
Audit Trail - Complete forensics

In v1.0+, the Go engine only loads schemas from the vault. Direct file loading is disabled for security.

Migration Registration

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

Features

✅ Immutable snapshots - Once registered, never modified
✅ SHA256 hash verification - Tamper detection on every operation
✅ Lineage tracking - Parent version references
✅ Automatic registration - On every migrate
✅ Complete audit trail - integrity.log never deleted
✅ Zero configuration - Auto-initializes on first use

Best Practices

Never manually edit vault files - Always use chameleon CLI
Commit vault to version control - Track schema history alongside code
Set mode password - Protect against unauthorized schema changes
Review integrity.log regularly - Monitor for unexpected changes
Use readonly mode in production - Prevent accidental modifications

Commands

# Initialize vault
chameleon init

# View version history
chameleon journal schema

# View specific version
chameleon journal schema v002

# Verify integrity
chameleon verify

# View vault status
chameleon status

# View integrity log
cat .chameleon/vault/integrity.log

Next Steps

Learn about Integrity Modes for runtime governance
Understand the Schema Language
Explore the Architecture

Get Started

Core Concepts

Schema Language

Query System

Mutations

Guides

Security

Overview

The Problem

The Solution

Vault Structure

manifest.json

versions/

hashes/

integrity.log

How It Works

1. Define Your Schema

2. Initialize the Vault

3. Apply Migration

4. Automatic Verification

5. Tamper Detection

Version History

Workflow

Security Model

Migration Registration

Features

Best Practices

Commands

Next Steps

​Overview

​The Problem

​The Solution

​Vault Structure

​manifest.json

​versions/

​hashes/

​integrity.log

​How It Works

​1. Define Your Schema

​2. Initialize the Vault

​3. Apply Migration

​4. Automatic Verification

​5. Tamper Detection

​Version History

​Workflow

​Security Model

​Migration Registration

​Features

​Best Practices

​Commands

​Next Steps

Overview

The Problem

The Solution

Vault Structure

manifest.json

versions/

hashes/

integrity.log

How It Works

1. Define Your Schema

2. Initialize the Vault

3. Apply Migration

4. Automatic Verification

5. Tamper Detection

Version History

Workflow

Security Model

Migration Registration

Features

Best Practices

Commands

Next Steps