Ptah ecosystem

To plan and apply a schema change you need one repository: ptah, which holds the engine and the CLIs. The other public repositories install it, run it for you on Kubernetes, add an engine it does not build in, or check it. Use the map to find the ones your work needs, and leave the rest out.

Ecosystem map

Full sizeDownloadSource

Core

• CLI / automationYour shell, scripts or CI→ ptah: Runs directly→ Kubernetes API: Manages with kubectl
• ptahEngine, CLIs and Go API→ ptah-ydb-plugin: Starts the provider (experimental)→ ptah-duckdb-plugin: No services yet (not implemented)→ ptah-spanner-plugin: Starts the provider when installed (experimental)

Optional Kubernetes workflow

• Kubernetes APIOperator resources→ ptah-operator: Reconciled by
• ptah-operatorKubernetes reconciler→ ptah: Runs executor Jobs
• ptah-consoleOptionalOperator web console→ Kubernetes API: Reads and approves as you

Optional external providers

• ptah-ydb-pluginExperimentalYDB provider
• ptah-duckdb-pluginScaffoldDuckDB provider
• ptah-spanner-pluginOptionalSpanner provider

Distribution and CI

• homebrew-ptahHomebrew tap→ ptah: Installs release and edge builds
• ptah-actionGitHub Action→ ptah: Runs on pull requests

Discover and try

• ptah.runWebsite and installers→ ptah: Serves the installers→ ptah-sandbox: Links to the playground
• ptah-sandboxBrowser playground→ ptah: Runs it as WebAssembly

Verification and test helpers

• ptah-atlas-conformanceAtlas compatibility evidence→ ptah: Measures compatibility
• ptah-testkitTest helpers for Go projects→ ptah: Wraps the Go API
• ptah-action-e2eAction end-to-end checks→ ptah-action: Tests it end to end

Legend

• Runs or calls
• Installs
• Tests or measures
• Documents or links
• Hollow arrowhead: experimental
• Sparse dashes: not implemented
• Dashed outline: not a repository

The public Ptah repositories, grouped by role, with ptah at the center.

What to notice: the direct path from the CLI to ptah needs nothing else. The Kubernetes workflow and the console are optional. So are the external providers, which only an engine Ptah does not build in needs.

Choose a path

Each path below is complete on its own, and the first one needs no other component. Start with the first unless your databases are managed from Kubernetes.

CLI or CI. Run ptah from a shell, a script or a CI job, or through the GitHub Action. This path needs no operator and no console.

• CLI / automation → ptah: Runs directly
• ptah-action → ptah: Runs on pull requests

Read next: Get a first result, Run Ptah in CI, Embed Ptah in Go.

Kubernetes. Install the operator and manage its resources with kubectl and the kubectl ptah plugin. The operator reconciles them and runs Ptah in short-lived executor Jobs.

• CLI / automation → Kubernetes API: Manages with kubectl
• Kubernetes API → ptah-operator: Reconciled by
• ptah-operator → ptah: Runs executor Jobs

Read next: Kubernetes operator, Operator documentation.

Kubernetes with the console. Add the console to the Kubernetes path when people want a browser view to inspect plans and approve them. It works through the same Kubernetes resources and replaces neither the operator nor Ptah.

• ptah-console → Kubernetes API: Reads and approves as you
• Kubernetes API → ptah-operator: Reconciled by
• ptah-operator → ptah: Runs executor Jobs

Read next: ptah-console, Console compatibility.

Providers are a separate choice, and they apply on any path. A provider is needed only for an engine Ptah does not build in. Supported databases lists what Ptah builds in, and executable providers explains how a provider is installed and selected.

What each repository does

Every public repository is listed here, and each row names what its owner says about its maturity. A repository’s existence is not a support claim: a scaffold can be recognized by Ptah and still do nothing.

Repository	Status	Use it when	Read next
Core
ptah Engine, CLIs and Go API	Released	Always. Every other component runs, installs, checks or links to it.	Releases Install Ptah Embed Ptah in Go
Optional Kubernetes workflow
ptah-operator Kubernetes reconciler	Released	Your databases are managed from Kubernetes, and changes should be reconciled from published artifacts with approvals bound to the exact plan.	Operator documentation Ptah compatibility Kubernetes operator
ptah-console Operator web console	Released	People review or approve operator plans and want a browser view instead of kubectl. The operator runs the same without it, and removing it changes nothing the operator does.	Compatibility
Optional external providers
ptah-ydb-plugin YDB provider	Experimental	You work with YDB. Install it with ptah providers install ydb; no Ptah installation channel includes it.	Configure the YDB provider Executable providers
ptah-duckdb-plugin DuckDB provider	Scaffold	Not for DuckDB work yet. Ptah has no built-in DuckDB support either.	Configure the DuckDB provider
ptah-spanner-plugin Spanner provider	Experimental	You work with Spanner's PostgreSQL interface. Install it with ptah providers install spanner; no Ptah installation channel includes it, and it installs no PGAdapter.	Configure the Spanner provider Executable providers
Distribution and CI
homebrew-ptah Homebrew tap	Released	You install command-line tools on macOS or Linux with Homebrew.	Install with Homebrew
ptah-action GitHub Action	Released	You review schema changes in GitHub pull requests.	Run Ptah in CI
Discover and try
ptah.run Website and installers	Published site	You meet Ptah for the first time, or you want the one-line install command.	Website
ptah-sandbox Browser playground	Published site	You want to try Ptah's commands before you install anything.	Playground
Verification and test helpers
ptah-atlas-conformance Atlas compatibility evidence	Evidence	You want to know what Atlas expresses that Ptah does not cover yet, before you rely on ptah-compat.	Conformance
ptah-testkit Test helpers for Go projects	Released	Your Go tests apply migrations to a real database.	Embed Ptah in Go
ptah-action-e2e Action end-to-end checks	Test fixture	You maintain the Action. Workflows that use the Action do not need it.	Nothing further

The status column uses these labels:

• Released. Publishes versioned releases.
• Experimental. Publishes releases and is still under development.
• Scaffold. Exists with no working features yet.
• Published site. A website, deployed from the repository.
• Evidence. Produces reports; not something you install.
• Test fixture. Exists to test another repository.

How the pieces connect

An arrow follows the flow of work, from the component that starts it to the one that carries it on. Not every connection is a runtime dependency: installing, testing and linking are different relationships, and the table names each one.

Relationship	Kind
CLI / automation → ptah: Runs directly	Runs or calls
CLI / automation → Kubernetes API: Manages with kubectl	Runs or calls
ptah-console → Kubernetes API: Reads and approves as you	Runs or calls
Kubernetes API → ptah-operator: Reconciled by	Runs or calls
ptah-operator → ptah: Runs executor Jobs	Runs or calls
ptah → ptah-ydb-plugin: Starts the provider (experimental)	Runs or calls
ptah → ptah-duckdb-plugin: No services yet (not implemented)	Runs or calls
ptah → ptah-spanner-plugin: Starts the provider when installed (experimental)	Runs or calls
homebrew-ptah → ptah: Installs release and edge builds	Installs
ptah.run → ptah: Serves the installers	Installs
ptah-action → ptah: Runs on pull requests	Runs or calls
ptah.run → ptah-sandbox: Links to the playground	Documents or links
ptah-sandbox → ptah: Runs it as WebAssembly	Runs or calls
ptah-atlas-conformance → ptah: Measures compatibility	Tests or measures
ptah-testkit → ptah: Wraps the Go API	Tests or measures
ptah-action-e2e → ptah-action: Tests it end to end	Tests or measures

Releases and compatibility

Ptah, the operator, the console and the providers have separate releases, and a new version of one does not imply a matching version of another. Each project publishes its own compatibility statement, so this page lists no version numbers:

• Ptah publishes its releases, and the support matrix lists the database release lines it covers.
• The operator runs a Ptah release image in its Jobs and publishes which Ptah build each operator release runs.
• The console is built against one operator release and publishes which console release goes with which operator release.
• A provider declares the provider contract it needs, and executable providers explains how Ptah picks a release it can run.
• Atlas compatibility is measured in ptah-atlas-conformance, and conformance reports what those runs show.

Next steps

• To run your first schema change from a terminal, follow Get a first result.
• To check changes on pull requests, read CI integration.
• To manage databases from Kubernetes, read Kubernetes operator.