Explore the YDB walkthrough

Understanding the provider boundary explains the components and messages of one YDB example, and What a comparison may conclude changes one fact of it at a time. The figure puts both on one screen. Select a component, an object or a connection to read about it, step through the workflow, and switch the scenario to see which step its changed fact changes.

The figure shows fixed facts from the walkthrough and from the tests behind it. It connects to no database and installs nothing.

YDB walkthrough

Components

• Ptah CoreHost: the ptah binary
• Contract and SDKBoundary between Core and the provider
• YDB providerProvider: the ptah-plugin-ydb executable
• YDB serverThe database

Objects of the example

• ordersRow table shop/orders
• orders/feedChangefeed of orders, with its topic shop/orders/feed
• ingest_ordersTransfer shop/ingest_orders
• orders_archiveRow table shop/orders_archive

Connections

Data flow in YDB

• orders → orders/feed: row changes, written by YDB
• orders/feed → ingest_orders: messages, read by the transfer
• ingest_orders → orders_archive: rows, written by YDB

Call

• Ptah Core → YDB provider: DecodeSource and NormalizeValues
• Ptah Core → YDB provider: Describe and Open
• Ptah Core → YDB provider: Inspect
• Ptah Core → YDB provider: CompareModels
• Ptah Core → YDB provider: PlanFeatures
• Ptah Core → YDB provider: Render and Execute
• YDB provider → YDB server: catalog reads
• YDB provider → YDB server: YQL statements

Model dependency

• ingest_orders → orders/feed: reads it; the transfer names its topic as a required object
• ingest_orders → orders_archive: writes it; it has to be a declared table
• orders/feed → orders: is a facet of it and exists only with it

Execution order

• orders → orders/feed: the table is created before its changefeed
• orders/feed → ingest_orders: the changefeed is created before the transfer
• orders_archive → ingest_orders: the target table is created before the transfer

Ptah Core, the contract, the YDB provider and the YDB server, with the four objects of the example and the connections between them.

What to notice: the data flow runs inside YDB after Ptah exits, and every call between Core and the provider crosses the contract. Step through a scenario to see where its changed fact changes the result.

The walkthrough as text

The tables below hold every fact the figure shows, for a reader without JavaScript and for the page’s Markdown copy.

Components

Component	Responsible for	Understands	Does not own
Ptah Core (Host: the ptah binary)	Loads the declaration, compares common tables, routes provider models to their owners, orders the whole plan, prints and applies it.	Common tables, identities and coverage. A provider payload only as bytes.	What a transfer means, or whether its source will exist after the plan.
Contract and SDK (Boundary between Core and the provider)	Defines the messages and features both sides agree on. The SDK checks each request and answer against them.	Message shapes, identities, representations and coverage records.	YDB meaning: a well-formed request can still describe a plan YDB would refuse.
YDB provider (Provider: the ptah-plugin-ydb executable)	Reads the YDB catalog, compares the models it owns, proposes plan steps, renders and runs YQL.	YDB semantics: changefeeds, topics, transfers and what each one needs.	Common tables, the order of the whole plan, and migration history policy.
YDB server (The database)	Stores the tables, keeps the changefeed and its topic, and runs the transfer after Ptah exits.	YQL statements and its own catalog.	The declaration, the comparison and the plan.

Objects

Object	In YDB	In Ptah	Compared by
orders	Row table shop/orders	A common table; its YDB settings are a row-table-properties facet	Ptah Core for the table; ydb-row-table-properties for the facet
orders/feed	Changefeed of orders, with its topic shop/orders/feed	One entry in the table-changefeeds facet of orders	ydb-row-table-properties
ingest_orders	Transfer shop/ingest_orders	A provider object of kind transfer	ydb-transfers
orders_archive	Row table shop/orders_archive	A common table	Ptah Core

Object	In the ydb-transfers request	Plan step
orders	declaredRelations, as a declared table	CREATE TABLE shop/orders
orders/feed	declaredFacets, as a changefeed orders declares; currentContext, once a read finds it	ALTER TABLE shop/orders ADD CHANGEFEED feed, then ALTER TOPIC shop/orders/feed ADD CONSUMER archiver
ingest_orders	desired, as the declared transfer; current, once it exists	CREATE TRANSFER shop/ingest_orders FROM shop/orders/feed TO shop/orders_archive
orders_archive	declaredRelations, as a declared table	CREATE TABLE shop/orders_archive

Workflow steps

Step	Who acts	What happens	Result in a normal creation
1. Declaration	Ptah Core, Contract and SDK, YDB provider	Core loads schema.yaml. The provider decodes the YDB extensions, the changefeed and the transfer, and the SDK checks their values.	The declared tables in Core’s common model, and normalized values of the changefeed set and the transfer.
2. Selection	Ptah Core, Contract and SDK, YDB provider	Core starts the provider and asks what it serves. Both agree on features, such as models.current-context, and the provider opens a session.	A session on the database and the list of features both sides negotiated.
3. Reading	Ptah Core, YDB provider, YDB server	The provider reads the selected directory, shop, and says what it established about each kind.	Nothing in shop, and coverage that says shop was read completely.
4. Comparison	Ptah Core, Contract and SDK, YDB provider	Core compares the common tables and sends each owner a request. ydb-transfers receives the declared transfer with the facts it needs about other owners.	A request with both tables in declaredRelations and the changefeed in declaredFacets.
5. Changes or refusal	YDB provider	Each owner returns changes or refuses one and says why. ydb-transfers checks the transfer’s source and target first.	Two new tables from Core, a new changefeed from ydb-row-table-properties and a new transfer from ydb-transfers.
6. Planning	Ptah Core, Contract and SDK, YDB provider	The provider turns its changes into steps and says which steps depend on which. Core checks them and orders the whole plan.	Four operations, the transfer last, after its changefeed and both tables.
7. Review and execution	Ptah Core, YDB provider, YDB server	Core prints the plan. On apply, the provider renders YQL and runs it, and YDB starts the transfer.	The statements run, and a row written to orders reaches orders_archive.
8. Reinspection	Ptah Core, YDB provider, YDB server	The next run reads and compares again.	Schema is synced, no changes to be made.

Scenarios

Scenario	Changed fact	Decided by	Outcome
Normal creation	Every object is declared, and shop is empty.	Each owner reports its own changes; Core orders them.	Four operations; the transfer is created last.
Valid no-op	Every object is declared, and the database already holds all four as declared.	ydb-transfers runs its dependency checks, and they pass.	Schema is synced, no changes to be made.
Missing source	The schema leaves out the changefeed feed of orders, and the database has none.	ydb-transfers, before anything is planned.	Refused: the transfer reads a topic the plan leaves absent.
Unrepresentable source, current context	The tables exist, and orders holds a changefeed whose consumer names a codec Ptah does not declare. The schema leaves the changefeed out. The host and the provider negotiate models.current-context.	ydb-transfers, from the current context.	The transfer is created; the plan neither drops nor changes the changefeed.
Unrepresentable source, no current context	The same database and schema, with a host or a provider that does not negotiate models.current-context, such as Ptah v0.24.1 or YDB plugin v0.7.0.	ydb-transfers, without the read’s facts about changefeeds.	Refused as a transfer of a missing topic.

Steps whose result differs from a normal creation:

Scenario	Step	Result
Valid no-op	Reading	All four objects, as the read found them, and complete coverage of shop.
Valid no-op	Comparison	A request with the transfer in desired and in current, and the changefeed set of orders in currentContext.
Valid no-op	Changes or refusal	No change: the source and the target are declared, and the transfer matches its declaration.
Valid no-op	Planning	Nothing to plan.
Valid no-op	Review and execution	Nothing runs: Schema is synced, no changes to be made.
Missing source	Comparison	A request in which declaredFacets holds no changefeed of orders, and currentContext holds none.
Missing source	Changes or refusal	Refused: it reads topic shop/orders/feed, which the schema declares neither as a topic nor as a changefeed, so the plan leaves no such topic.
Missing source	Planning	Not reached: the run stops at the refusal.
Missing source	Review and execution	Not reached: the run stops at the refusal.
Missing source	Reinspection	Not reached: the run stops at the refusal.
Unrepresentable source, current context	Reading	Both tables, and the changefeed set of orders recorded as unrepresentable, with no value.
Unrepresentable source, current context	Comparison	A request whose currentContext carries that coverage record of orders.
Unrepresentable source, current context	Changes or refusal	One new transfer. Its source stays after the plan, because the plan does not drop what the read could not describe.
Unrepresentable source, current context	Planning	One operation: the transfer.
Unrepresentable source, current context	Review and execution	CREATE TRANSFER runs. Nothing checked the changefeed’s definition.
Unrepresentable source, current context	Reinspection	Nothing to plan for the transfer.
Unrepresentable source, no current context	Selection	A session, without models.current-context among the negotiated features.
Unrepresentable source, no current context	Reading	Both tables, and the changefeed set of orders recorded as unrepresentable, with no value.
Unrepresentable source, no current context	Comparison	A request without currentContext.
Unrepresentable source, no current context	Changes or refusal	Refused: it reads topic shop/orders/feed, which the schema declares neither as a topic nor as a changefeed.
Unrepresentable source, no current context	Planning	Not reached: the run stops at the refusal.
Unrepresentable source, no current context	Review and execution	Not reached: the run stops at the refusal.
Unrepresentable source, no current context	Reinspection	Not reached: the run stops at the refusal.

The test that measures each scenario:

Scenario	Test
Normal creation	TestHostCreatesATransferAfterItsChangefeed_HappyPath
Valid no-op	TestHostCreatesATransferAfterItsChangefeed_HappyPath
Missing source	TestHostRefusesATransferOfAnUndeclaredChangefeed_FailurePath
Unrepresentable source, current context	TestHostCreatesATransferOfAChangefeedItCannotDescribe_HappyPath
Unrepresentable source, no current context	TestTransferComparisonAcceptsARecordedSource_FailurePath

Connections

Connection	Kind
orders → orders/feed: row changes, written by YDB	Data flow in YDB
orders/feed → ingest_orders: messages, read by the transfer	Data flow in YDB
ingest_orders → orders_archive: rows, written by YDB	Data flow in YDB
Ptah Core → YDB provider: DecodeSource and NormalizeValues	Call
Ptah Core → YDB provider: Describe and Open	Call
Ptah Core → YDB provider: Inspect	Call
Ptah Core → YDB provider: CompareModels	Call
Ptah Core → YDB provider: PlanFeatures	Call
Ptah Core → YDB provider: Render and Execute	Call
YDB provider → YDB server: catalog reads	Call
YDB provider → YDB server: YQL statements	Call
ingest_orders → orders/feed: reads it; the transfer names its topic as a required object	Model dependency
ingest_orders → orders_archive: writes it; it has to be a declared table	Model dependency
orders/feed → orders: is a facet of it and exists only with it	Model dependency
orders → orders/feed: the table is created before its changefeed	Execution order
orders/feed → ingest_orders: the changefeed is created before the transfer	Execution order
orders_archive → ingest_orders: the target table is created before the transfer	Execution order