This is the official, separately installed YDB plugin for Ptah. It reads YDB schemas, compares them with a desired schema, plans and applies supported changes, and runs migrations through Ptah's common workflow. The plugin owns YDB connections, YQL, catalog interpretation, native objects, and execution. Ptah itself contains no built-in YDB engine.
Install the newest provider release compatible with your Ptah executable, then check the installed copy:
ptah providers install ydb
ptah providers check --provider-engine ydb --jsonA successful check reports "status": "compatible". To choose a release explicitly, pass --version 0.8.0 to ptah providers install ydb; the version has no leading v. A ydb:// or ydbs:// URL, or the ydb dialect, then selects the installed provider automatically. Ptah's install guide explains release selection, verification, and explicit manifests.
Start a reachable YDB server with a database at /local. The example URL uses the local development server without credentials and disables endpoint discovery, so it also works through a port forward. Use your own database URL and authentication settings for another server.
ptah schema inspect --db-url 'ydb://localhost:2136/local?go_balancer=disable' --format sqlThis prints the inspected schema as YQL. The output depends on the objects in your database. For connection parameters and TLS, see Using the provider with Ptah and Connection addresses. The schema and migration guide covers the next steps in Ptah.
The provider handles row and column tables, indexes, topics, changefeeds, coordination nodes, external objects, resource pools, secrets, replications, transfers, streaming queries, and the YDB-specific parts of access control. It also implements migration history, locks, YQL analysis and lint, and offline source handling. Supported operations and declarations vary by object, source format, negotiated feature, and YDB release line. Start with the object primer, then use the reference pages below for exact behavior.
YDB schema changes are not transactional. An inspection or export can report incomplete catalog coverage or a format-specific loss; read those diagnostics before treating a file as a complete copy of a database. The provider's declared release lines are in source: CI exercises YDB 25.1 and 26.2, while the intermediate declared lines are best effort. Server features can further limit an operation.
The provider advertises security.vulnerability-scan and security.advisory-snapshot at provider and YDB engine scope. It bundles the reviewed YDB server advisories and sends them to Ptah with its engine description. Ptah reads SELECT Version() during connection setup and matches that version against the provider's snapshot. Neither process downloads advisories during a scan or inspects application dependencies. The daily source check updates the snapshot through a review pull request.
For a self-managed YDB server, run ptah db vulnerabilities --db-url "$DATABASE_URL". The default deployment is self-managed. If the service operator controls server patching, pass --deployment managed; Ptah then reports not_applicable and does not match server CVEs. The endpoint alone does not establish who patches the server. See the vulnerability scan guide for source coverage and CI policy.
The built-in YDB implementation was removed from Ptah. Official providers are installed separately; they are not bundled with a Ptah release. The parity tracker is closed, and release archives and verification workflows are in use. Limits are described by operation in the reference pages, rather than as an unfinished extraction checklist.
The release's ptah-provider.json states its minimum host contract; the provider's Description supplies the same minimum. The SDK version is pinned in go.mod. These are different from the Ptah release number and from features negotiated after startup. At this revision the minimum is contract 25.7. A specific operation can require a newer host: for example, the v0.8.0 transfer fix needs Ptah v0.25.0 and contract 25.40. That requirement does not change the provider's startup minimum.
The published YDB setup page is the entry point on docs.ptah.run. The source pages below are available in this repository immediately; the website imports them from a selected provider release.
| Task | Page |
|---|---|
| Connect and use Ptah or ptah-compat | Usage |
| Understand YDB objects | Object primer |
| Write Go annotations or YAML declarations | Declarations |
| Run migrations | Migrations |
| Use embedding generations | Inference |
| Connections, execution, history, and catalog reads | Runtime reference |
| Offline models, comparison, and source conversion | Schema model reference |
| Native YDB object planning and execution | Object lifecycle reference |
| Table and column changes | Table lifecycle reference |
| YQL, lint, rows, and rendering | SQL and data reference |
The documentation index maps more specific topics. To build, test, or release the plugin, read Contributing.
Former README section links
Detailed sections moved to the reference pages. These anchors keep existing links to this README useful; follow the corresponding reference link for the current text.
| Former section | Current location |
|---|---|
| Releases | Contributor release reference |
| Async replications and transfers | Open section |
| Build and test | Open section |
| Changefeeds | Open section |
| Column addition and removal | Open section |
| Column families | Open section |
| Column tables | Open section |
| Common column semantics | Open section |
| Common objects | Open section |
| Comparison counts | Open section |
| Connection addresses | Open section |
| Coordination comparison | Open section |
| Coordination locks | Open section |
| Dev database cleanup | Open section |
| Dev databases | Open section |
| Dev realms | Open section |
| Embedding store | Open section |
| Error reasons | Open section |
| Execution | Open section |
| Execution and transactions | Open section |
| External data sources and external tables | Open section |
| Extraction still required | Open section |
| Feature flags | Open section |
| Index alteration | Open section |
| Index declarations of the providers types | Open section |
| Index settings from a source | Open section |
| Migration history | Open section |
| Migration journals and tags | Open section |
| Migration lint | Open section |
| Migration splits | Open section |
| Native cli development acceptance | Open section |
| Native coordination planning and execution | Open section |
| Native protocol generation | Open section |
| Native row table creation | Open section |
| Native table alteration | Open section |
| Native table rebuild | Open section |
| Native table removal | Open section |
| Object counts | Open section |
| Offline capabilities | Open section |
| Offline column declarations | Open section |
| Offline column storage observations | Open section |
| Offline coordination declarations | Open section |
| Offline create prediction | Open section |
| Offline index and stream declarations | Open section |
| Offline native object declarations | Open section |
| Offline row table declarations | Open section |
| Offline schema rendering | Open section |
| Offline schema validation | Open section |
| Offline sql analysis | Open section |
| Offline table preparation | Open section |
| Operational storage reservations | Open section |
| Operator statements and object scopes | Open section |
| Partitioning settings read replicas and key bloom filter | Open section |
| Resource pools and classifiers | Open section |
| Reverse migrations | Open section |
| Row table model conversion | Open section |
| Rows row writes and seeds | Open section |
| Schema observations | Open section |
| Secrets | Open section |
| Serial columns | Open section |
| Sql schema reading | Open section |
| Statement facts for ptah sql lint | Open section |
| Streaming queries | Open section |
| Table property comparison | Open section |
| Text scanning | Open section |
| Text units | Open section |
| Topics | Open section |
| Ttl | Open section |
| Vector and full text indexes | Open section |