Create your own workspace

Use the installed CLI to generate and adapt a workspace without connecting to a server. This guide starts from the same cross-source model as the runnable Quickstart, then shows where to replace the sample connections, table selection, and document shape.

Offline validation checks the resource contract. It does not test a database connection, create the managed view store, or run the pipeline.

What you will create

tapstate-work/
├── source/
│   ├── orders_db.tap.yml
│   └── fulfillment_db.tap.yml
└── pipeline/
    └── order_pipeline.tap.yml

The two source resources describe MySQL orders and PostgreSQL shipments. The pipeline uses nest to assemble related rows and declares an inline order_state view. The view is materialized by the running deployment; it is not an external MongoDB target in the workspace.

Before you begin

• Install the tapstate CLI. Command availability can vary by tapstate version.
• Keep credentials in environment variables or your deployment's secret mechanism.
• Read the MySQL and PostgreSQL preparation guides.
• Use non-production credentials and endpoints for an authoring walkthrough.

Check the installed command first:

tapstate --version

If the command is unavailable, install it before continuing.

1. Generate the workspace

tapstate demo --workdir tapstate-work

The command writes the three files shown above. It does not start Docker, connect to a server, or run the pipeline. Use a new directory; the command refuses to overwrite an existing demo workspace unless you pass --force.

To inspect the walkthrough without writing files:

tapstate demo --print-steps

2. Configure your source connections

Open both files under tapstate-work/source/ and replace the sample config values with endpoints and credentials for your non-production databases. Keep the connector-owned field names distinct: MySQL uses username; PostgreSQL uses user and includes schema.

The generated sources use mode: cdc, and the pipeline uses read_mode: snapshot_and_cdc. Prepare binary logging and PostgreSQL logical replication before testing this path. If you need only a bounded initial copy, change the source and pipeline modes according to Capture modes.

Use environment-variable placeholders or your deployment's secret mechanism. Do not commit literal credentials.

3. Select your tables and document shape

The generated pipeline expects orders from orders_db and shipments from fulfillment_db. If your tables or keys differ, update these parts together:

• each source's tables selection;
• the aliases in the nest.from map;
• root.from and root.key for the parent record;
• embed.from, embed.on, and arrayKey for child records;
• the inline view's id, from, and primary_key.

Use Assemble documents with nest for the complete shape and key rules. Keep IDs and references consistent across all three files.

4. Validate the workspace offline

tapstate validate --workdir tapstate-work

An exit code of 0 means the installed validator accepted the resource structure, references, modes, and recognized connector fields.

Offline validation does not require every catalog-required connection field, reject unknown connector keys, inspect environment-variable values, or open a network connection. For example, a syntactically valid resource that points to mysql.invalid can pass this step.

Server-side apply can run additional checks after schema discovery. In particular, an external serve.sync upsert requires a primary key in every selected source table's discovered schema.

5. Inspect the resources

Use these commands to review the workspace and field grammar:

tapstate ls --workdir tapstate-work
tapstate desc order_pipeline --workdir tapstate-work
tapstate explain source.mode

Do not infer runtime success from an authoring or inspection command.

Extend the pipeline

Use the same workspace as the starting point for the next capability you need:

When you are ready to run the workspace, register the official connectors, apply and discover both sources, apply the complete workspace, and then start the pipeline. See Register and test connectors and Apply and run a pipeline. For runtime signals, use Observe a pipeline.

Next steps

• Apply and run the pipeline against a non-production server.
• Observe the pipeline after it starts.
• Use the resource definitions when you need an exact field shape.
• Use Troubleshooting to isolate authoring, deployment, and data problems.