Skip to content
stokaroPublic

Latest commit

 

History

4,627 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

The Ptah mark: an amber capstone above two sky-blue courses on a dark rounded square

Ptah

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

English · 日本語 · Deutsch · Français

Status of the unit test workflow on the master branch Status of the integration test workflow on the master branch Status of the capability matrix workflow on the master branch, which probes every declared database release line The latest published release tag The Go package reference for ptah.run The lowest Go version this module compiles against, declared in go.mod The license badge, reading MIT

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

PostgreSQL    MySQL    MariaDB    SQLite    SQL Server    ClickHouse    CockroachDB    YugabyteDB    Oracle    Spanner    YDB

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

Schema sources and the live database produce a reviewable plan for versioned migrations or direct apply. Inference builds and verifies a candidate before cutover; rollback restores an eligible previous generation.

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.

Prepare, backfill, catchup, index, and verify a candidate while the current generation serves queries. Cutover activates the candidate. Rollback restores an eligible previous generation. Retirement separately destroys an inactive generation with no eligible rollback dependency.

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.

YDB

YDB is supported through the official provider stokaro/ptah-ydb-plugin. It is installed separately, with a command of Ptah's own; the ptah binary, the archives and the container images carry no YDB code:

ptah providers install ydb

After the install, a command that names a ydb:// or ydbs:// URL, or the ydb dialect, uses the provider without a flag or a manifest. The provider plans, applies and reads YDB tables, native objects and views, runs versioned migrations, lints YQL and writes data, on YDB 25.1 and 26.2. Configure the YDB provider covers selection with a manifest, verification and the refusal codes.

DuckDB

Ptah supports embedded DuckDB through the official DuckDB plugin. Install it separately from Ptah:

ptah providers install duckdb

Use a duckdb:// URL to inspect a local file or in-memory database, plan and apply schema changes, and run versioned migrations. The plugin contains the native DuckDB library; the Ptah binary has no DuckDB dependency. MotherDuck and other network targets are outside this provider's scope. See the DuckDB provider guide for setup, supported operations, and limitations.

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

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. The Atlas vs Ptah comparison explains licensing, workflows, database coverage, and where the tools differ.

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.

Ask questions and share ideas in Discussions; report bugs and request features in the issue tracker. CONTRIBUTING.md covers what makes a report actionable and what a change has to pass, and participation is covered by the Code of Conduct. Commercial enquiries go to ask <at> stokaro.com.

Releases

Packages

Used by

Contributors

Languages