Apply and run a pipeline

Apply turns local drafts into server-held resources. Lifecycle commands then write the desired state that the runtime converges toward.

Before you begin

• Validate the workspace locally.
• Register the required connector JARs.
• Apply and test source and target connections from the server environment.
• Use a non-production data set for the preview.

See Register and test connectors for the preceding sequence.

Apply the workspace

Start an authenticated session in the workspace:

tapstate -w work

connect http://127.0.0.1:8080
login admin
apply

With no operand, apply sends the workspace as one batch. To apply one file or directory:

apply source/orders_source.tap.yml

The server reparses and validates each draft. The result reports:

• CREATED for a new artifact;
• UPDATED when canonical content changed;
• UNCHANGED when the stored content hash already matches.

Some checks require the source's discovered schema and therefore run only on the server. If apply returns dsl.upsert-needs-key, every selected source table written with the default upsert mode needs a discovered primary key. Discover the source again and select keyed tables, or use append only when the delivery is insert-only. A unique index or tables[].pk does not satisfy this runtime check.

Confirm the server-held resources:

ls
get orders_source
get orders_to_operational_state

Local files remain authoring input; connected get and ls show the server's current truth.

Start the pipeline

start orders_to_operational_state
status orders_to_operational_state --watch

start writes a RUNNING intent at the latest applied pipeline revision. status --watch reports observed runtime state, which can lag the command briefly.

Verify data at the destination. A lifecycle command succeeding proves that the intent was accepted, not that rows arrived.

Lifecycle transitions

An illegal transition returns lifecycle.illegal-transition. If a paused pipeline was reapplied, resume can return lifecycle.incompatible-revision; stop it, review the change, then start a fresh run.

Recover a failed pipeline deliberately:

logs orders_to_operational_state
stop orders_to_operational_state
start orders_to_operational_state

Do not start directly from FAILED.

Verify the outcome

Use all three evidence types:

1. status reaches the expected state;
2. metrics and logs show active work without unresolved errors;
3. source and destination queries show the expected snapshot and later insert, update, and delete behavior.

The preview is single-node and does not persist a resumable runtime offset across a server restart. A process restart can replay from the source even when pause/resume worked within the running deployment.

Next steps

• Observe a pipeline
• Troubleshooting
• Current preview boundaries