Ptah

Open-source database change management for schemas and persistent inference state.

Install · Quick start · Inference migrations · Documentation · Database support

                          

Ptah manages database change across schemas and persistent inference state. For schemas, it compares a desired schema with a live database and either writes versioned migrations or applies an approved plan directly. For inference state, it builds a candidate generation beside the active one, calls an external embedding endpoint, verifies the result, and switches consumers with a rollback path.

The command-line interface runs without a Go toolchain, and the same planning components are available as Go packages.

Schema changes

Both workflows use the same comparison and planning model. The difference is whether SQL becomes a reviewed artifact in version control before it runs.

Persistent inference state

Ptah orchestrates the migration; it does not run inference. It reads source rows, calls the external endpoint, and writes the candidate generation itself, leaving the active generation untouched until verification and cutover.

The inference migrations guide covers the specification, concurrent-change catch-up, evaluation, approvals, rollback, and retirement.

Note

Ptah is pre-GA. The native command tree and public Go API can still change.

Install

The installer selects the current release for Linux, macOS, or Windows, verifies its checksum, and installs ptah, ptah-compat, and ptah-ls under your home directory.

curl -fsSL https://ptah.run/install.sh | sh

In PowerShell:

irm https://ptah.run/install.ps1 | iex

The installation guide covers version pinning, signature verification, download-without-execution, and building from source.

Try Ptah with SQLite

Save this desired schema as schema.sql:

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    email TEXT NOT NULL UNIQUE
);

Render the SQL, apply it to a throwaway database, and check that the database matches the file:

ptah schema render --schema-file schema.sql --dialect sqlite
ptah schema apply --db-url "sqlite://app.db" --schema-file schema.sql --auto-approve
ptah schema drift --db-url "sqlite://app.db" --schema-file schema.sql

Expected output includes:

CREATE TABLE "users" (

Expected output includes:

Schema apply completed successfully.

Expected output includes:

No schema drift detected.

The last command exits 0 when the database matches the file, which is what makes it usable as a CI gate. Remove app.db and schema.sql when you are done.

Caution

--auto-approve skips the confirmation prompt. A direct schema change can drop objects that the desired schema does not declare. Use it here only because app.db is disposable.

For a complete workflow with expected output and verification, use the direct schema changes tutorial or the versioned migrations tutorial.

Choose how schema changes land

Workflow	Use it when	Start with
Versioned migrations	SQL files belong in code review and deployment history	ptah migrations generate
Direct schema changes	The desired schema is authoritative and you want to review and apply the plan now	ptah schema plan

Schema sources can come from SQL, YAML, HCL, DBML, Go annotations, external loaders, or a live database. Database and feature coverage vary by engine; use the support matrix and ptah db capabilities --db-url <url> for the concrete target.

Explore the documentation

• Choose a workflow to compare versioned migrations with direct schema changes.
• Inspect a live database or compare and detect drift.
• Validate migration integrity or test migrations and schemas.
• Visualize or export a schema.
• Migrate persistent inference state while an external endpoint computes embeddings.
• Look up native commands or diagnose a failure.

The site source lives in docs/site. docs/README.md indexes contributor and implementation documents outside the reader site.

Go packages and Atlas compatibility

Go projects can embed the documented packages, use annotated structs as schema sources, and run ptah-ls for editor support. Start with the public API ledger, reusable components, or Go annotations.

The separate ptah-compat binary exposes an Atlas-compatible command surface; the native ptah command tree does not use Atlas command paths. Ptah does not claim full Atlas parity. The compatibility overview and conformance results state the measured coverage and differences.

License and help

Ptah is an independent clean-room implementation published under the MIT license. It does not use Atlas source code and is not affiliated with or endorsed by Ariga. The license boundary records the provenance policy.

The database marks above identify the engines Ptah supports and nothing more. Each belongs to its owner, and none of those owners endorses or sponsors Ptah. NOTICE says where each file came from and under which license.

For questions and bug reports, open an issue in stokaro/ptah.