October 6, 20266 min read

Ptah 0.13.0: Native YDB Schemas and Migrations

Ptah 0.13.0 adds native YDB migrations and desired YQL schemas, expands dev databases, and improves locking and schema comparison across engines.

Nathan BrooksTechnical Writer

Ptah helps you plan, review, and apply database migrations. Try in your browser

Ptah 0.13.0 is available. You can now manage YDB schemas and migrations through native Ptah and Ptah Compat. A desired schema can come from Go annotations, YAML, or a YQL file, including the declarations and clauses of the supported YDB object families.

This release also expands disposable development databases and improves migration locking and schema comparison for existing engines. For YDB, we focused this stage on schemas and migrations. YDB inference remains a separate task.

Keep YDB settings in the desired schema

A table’s declaration includes more than its columns. An index can cover additional columns, a time-to-live (TTL) policy can delete expired rows, and a storage setting can change how reads work. Those choices need to survive reading the schema file and generating the SQL.

In 0.13.0, this YQL file is a desired schema:

CREATE TABLE `app/events` (
    id Int64 NOT NULL,
    account_id Int64 NOT NULL,
    body Utf8 DEFAULT 'pending'u,
    created_at Timestamp NOT NULL,
    PRIMARY KEY (id),
    INDEX by_account GLOBAL SYNC ON (account_id) COVER (body)
) WITH (
    TTL = Interval('P30D') ON created_at,
    KEY_BLOOM_FILTER = ENABLED
);

Save it as schema.sql and render it for your target YDB version:

ptah schema render --schema-file schema.sql --dialect ydb --server-version 26.2.1.14

The output retains the index’s covering column, deletion policy, and Bloom filter setting. This excerpt is from the end of the generated table:

    INDEX `by_account` GLOBAL SYNC ON (`account_id`) COVER (`body`)
) WITH (TTL = Interval("P30D") ON `created_at`, KEY_BLOOM_FILTER = ENABLED);

The command reads and renders the declaration without connecting to YDB or executing the input. The same reader supplies the desired state for planning and applying changes against a live database. The example files include the complete input and recorded output from 0.13.0.

The path app/events names a table under the database’s app directory. YDB uses paths rather than PostgreSQL-style schemas. The u suffix on 'pending'u makes the default an Utf8 literal. The index is part of CREATE TABLE, which is how YDB declares indexes on a new table.

Desired YQL also covers column tables, column families, views, topics, changefeeds and consumers, users and permissions, secrets, and external data sources and tables. Replication, transfers, coordination nodes, resource pools, and streaming queries belong to the same schema workflow. The YDB reference describes the accepted declarations and settings for each family.

These declarations express desired state. For example, removing TTL from a YQL table declaration requests removal of the existing deletion policy. Review the plan when changing or removing a clause.

Plan for the target server’s capabilities

YDB connects through ydb:// or ydbs://, using its native protocol and YQL. Both CLI surfaces share the implementation. In Ptah Compat, YDB is a Ptah extension; the strict Atlas Community compatibility mode refuses it.

Support depends on the server release and its enabled features. Our certified YDB lines are 25.1 and 26.2. An explicit server version selects the capabilities for offline rendering. When connecting to a cluster, Ptah can also read feature flags through a configured monitoring endpoint.

A capability the target lacks produces a refusal. For example, adding a unique index to an existing table requires a YDB feature flag that is off by default. Declaring the index with a new table is a different operation. Foreign keys and CHECK constraints are refused, and JSON indexes remain unsupported. These boundaries are part of planning, before an unsupported operation reaches the server.

Some changes require moving data. YDB cannot change a primary key or column type in place, or add NOT NULL to an existing column. Ptah refuses those changes by default. The explicit --allow-table-rebuild option permits a supported row-table rebuild through a new table, a copy, and a rename sequence.

A rebuild is not atomic. Stop application writes for its duration: rows written between the copy and the swap can be lost. The plan calls out that requirement, and Ptah still refuses rebuilds that would discard settings it cannot preserve. See the rebuild rules before choosing this path.

Run migrations within YDB’s transaction boundaries

YDB schema statements run outside transactions. A versioned migration therefore executes as a sequence of queries: each schema statement runs on its own, while consecutive data statements run in a transaction with their revision checkpoint. Generated migrations carry the required no-transaction mode.

Ptah records progress per query so an interrupted migration can resume from its checkpoint. That does not make schema changes transactional. Review an interrupted run before resuming it; a schema operation whose outcome is unknown needs attention. Mixed schema and data statements inside one query block are refused. The migration reference explains resume and timeout behavior.

Migration locking also improves across engines. A run that loses its migration lock stops guarded work. MySQL metadata-lock waits now honor the configured lock timeout, so that timeout bounds waiting inside the server as well.

Rehearse with a development database

Dev database provisioning now accepts custom images through docker+<driver>://, supports PostGIS and pgvector images, and provisions YDB. Ptah Compat also reads Docker blocks in atlas.hcl. Container ownership is scoped to the process, and startup reports a container that exits before it becomes ready.

Resetting a dev database preserves its baseline extensions, default privileges, event triggers, and publications. A database provisioned through a Docker block returns to its starting state after use, so a later comparison does not inherit objects from an earlier rehearsal.

For an existing YDB server, Ptah isolates dev and shadow work in a temporary directory under ptah_dev. Replay refuses operations that would escape that directory, including database-wide users and permissions. Use a disposable server when the rehearsal needs those operations. The dev database reference explains the distinction and cleanup behavior.

More accurate comparisons on existing engines

The release also fixes differences that could obscure a migration review:

Engine	Change in 0.13.0
SQL Server	Index `INCLUDE` columns survive rendering, inspection, and planning. Ordinary multi-column tables no longer fail a diff because of an unsupported column-order check.
ClickHouse	Comparisons use stored column types and declared key clauses. Changes to defaults and nullability produce the required operations.
CockroachDB	Comparisons account for catalog spellings of types, views, and routines. Implicit primary-key columns no longer create false index payload changes.
PostgreSQL family	Grants on sequences owned by serial or identity columns survive inspection, filtering, scoped comparison, and column renames.

Migration metadata stays outside application-schema comparisons. Compatibility configuration also evaluates data "composite_schema" through the shared schema merge and honors configured source kinds when --to is omitted.

Upgrade to 0.13.0

Use the installation guide or the images ghcr.io/stokaro/ptah:0.13.0 and stokaro/ptah:0.13.0. The archives and images include ptah, ptah-compat, and ptah-ls.

Generate and review a fresh plan before applying it. Corrected inspection can reveal a real difference that an older release missed; corrected comparison can remove a change that was never needed. For YDB, select the target server version and check the plan’s capability requirements.

The release notes include installation caveats, including macOS Gatekeeper handling. The full change list covers the remaining fixes and dependency updates.

Put Ptah to work

Example files

← All articles