Skip to content

Repository files navigation

Ptah YDB provider

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

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 --json

A 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.

First inspection

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 sql

This 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.

Capabilities and limits

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.

Server vulnerability scans

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.

Current status

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.

Documentation

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