Alpha - v1.2.0-alpha
ChameleonDB keeps a reliable relationship between the schema you declare, the changes you make to it, and the real state of your database. Open source, alpha, PostgreSQL only.
ChameleonDB helps you keep a reliable relationship between the schema you declare, the changes you make to it, and the real state of your database. It treats the schema as a versioned, hash-checked artifact, records every change in a local audit trail, and lets you restrict who may change the schema through integrity modes.
It is not a database engine or an ORM. Today it works with PostgreSQL only.
The near-term goal is to make schema change observable and reviewable: know how a database differs from what you think it has, and review every change together with its risk, without rewriting your existing setup first. The longer-term ambition is an adaptive platform for governing the lifecycle of data models across engines and environments.
That direction is a plan, not a description of the current code. See the product definition.
Declare entities, fields and relations in .cham files; parse and type-check them.
Preview the SQL with --dry-run, then apply it.
Each registered schema version is stored locally with a SHA-256 hash of its source text and its parent version.
Four modes (readonly, standard, privileged, emergency) decide whether schema changes are allowed.
The vault is checked before operations, and events go to an append-only log.
Generate a .cham schema from an existing PostgreSQL database. Review the result before relying on it.
A query and mutation builder with field selection, eager loading and write guards. A supporting component whose scope is under review.
The vault detects changes made to its files outside the tool. It does not protect against someone who can edit both the files and their hashes.
Integrity modes control what the CLI allows. They do not replace database permissions; a user with direct database access is not restricted by them.
The hash is computed over the schema source text, so formatting changes alter it. A canonical form is planned.
An update or delete without a filter is rejected with a SafetyError before it reaches the database. The check happens at runtime, in the data-access layer.
// Rejected: no filter.
_, err := db.Update("User").
Set("name", "New Name").
Execute(ctx)
// err is a SafetyErrorSince v1.1.0-alpha, query and mutation values are sent as bound parameters, and field names are validated against the schema and quoted.
The data-access layer is a supporting component; the schema language and vault are the core of the project.
entity User {
id: uuid primary,
email: string unique,
posts: [Post] via author_id,
}
entity Post {
id: uuid primary,
author_id: uuid,
author: User,
}user := db.Query("User").
Filter("email", "eq", email).
Include("posts").
Execute(ctx)
SELECT users.id, users.email
FROM users
WHERE users.email = $1;
Parameters:
$1 = email
Paste your schema and see the entity relationships as a diagram. Powered by Mermaid.js, validate your design before writing code.
See your database design in real-time
ChameleonDB is not an ORM and not a database engine. It focuses on the life of the schema: versioning, verification, auditability and restricted change. It is meant to sit next to the tools you already use, and the Go data-access layer is a supporting component, not the center of the project.
If you need a full-featured ORM, use one. If you want a verifiable history of your schema and control over who may change it, that is what ChameleonDB is for.
Ordered by priority, without dates. A plan, not a promise.
The code behaves predictably and its claims match reality.
Canonical model, introspection, baseline snapshots, drift reports.
Risk-classified plans, gates, verification of control level.
Additional adapters, integrations, collaboration.
Compatibility between revisions, sync-engine integration.
PostgreSQL is required. Integration tests run against PostgreSQL 16; other versions are not yet verified.
curl -sSL https://chameleondb.dev/install | shDownload the latest release from GitHub releases. Extract; keep chameleon.exe and chameleon.dll together; add the folder to PATH.
git clone https://github.com/chameleon-db/chameleondb.git
cd chameleondb
make buildGo 1.25.6 or newer, stable Rust, a C compiler, and make are required.
mkdir my-project && cd my-project
chameleon init
# write schema.cham, then:
chameleon check schema.cham
chameleon migrate --dry-run
chameleon config auth set-password
chameleon config set mode=standard
chameleon migrate --apply
chameleon journal schemaNew vaults start in readonly mode, which blocks schema changes. Raise the mode before applying a migration. See the examples repository.
A schema-first tool that versions and hash-checks your PostgreSQL schema, records changes in a local audit trail, and lets you restrict who may change the schema through integrity modes.
No. It also includes a Go data-access layer for queries and mutations, but that is a supporting component and its scope is under review.
Introspection can generate a .cham schema from an existing database. Review the result before relying on it.
Yes for migrations: chameleon migrate --dry-run prints the SQL without applying it.
They decide whether the CLI allows schema changes. They do not replace database roles; someone with direct database access is not restricted by them.
It detects changes made to its files outside the tool. It does not protect against someone who can edit both the files and their hashes.
PostgreSQL only, through the CLI and a Go library. No other language or engine is committed. The distribution and runtime strategy is being re-evaluated.
No. ChameleonDB is alpha: interfaces and file formats may change. Evaluate it on non-critical data first, and read the security notice if you use an earlier release.
Transaction support and an identity map in the Go data layer, additional databases, and drift detection (planned).
Privately, as described in SECURITY.md. Do not open a public issue.
See CONTRIBUTING.md. Feedback from people who manage PostgreSQL schema changes in real projects is especially valuable.
Watch the repository on GitHub (Watch, Custom, Releases) to be notified of new releases. Discussion happens on Discord.