Quickstart

Run one disposable tapstate data path without installing the CLI or preparing your own databases. The playground captures MySQL orders and PostgreSQL shipments, assembles them into one order document, and materializes the result in MongoDB.

When you finish, you will have a running order_pipeline and can read views.order_state from the tapstate CLI.

This quickstart is an evaluation environment, not a server installation or production deployment. Use sample data only.

Why assemble this state

The sample keeps order details in MySQL and fulfillment records in PostgreSQL. Neither database can join a table in the other, so an application that needs a complete order would otherwise query both systems and assemble the result on every request.

Tapstate declares that relationship once. An initial snapshot builds the current order state, and CDC keeps the same object fresh when either the order or one of its shipments changes.

Before you begin

You need:

• macOS or Linux;
• Docker with the Compose plugin running;
• curl;
• several GB of free Docker storage.

Confirm Docker is available:

docker info
docker compose version

You do not need to install the tapstate CLI. The script downloads the current published preview CLI, connector artifacts, and the Quickstart stack into a disposable tapstate-demo directory. The published CLI and server assets are selected from the same release path.

1. Start the playground

Run the published quickstart script:

curl -fsSL https://install.tapstate.dev | sh

The script starts MySQL, PostgreSQL, MongoDB, and a tapstate server. It then:

1. creates a local administrator;
2. registers the MySQL, PostgreSQL, and MongoDB connectors;
3. applies and discovers both source connections;
4. applies and starts order_pipeline;
5. waits for the assembled initial state.

The command can take several minutes the first time while Docker downloads the images.

For an unreliable connection, save the script before running it so you can inspect and rerun the same file:

mkdir -p tapstate-demo
cd tapstate-demo
curl -fL https://install.tapstate.dev -o quickstart.sh
sh quickstart.sh

The script retries interrupted asset downloads and keeps an incomplete transfer as a .part file. Run the same command again to resume it. A failed transfer does not count as a successful setup.

2. Confirm the result

A successful run ends with this line:

quickstart: 5 orders from MySQL, each carrying its shipments from PostgreSQL -- 6 of them, in one object per order

Do not treat a healthy container or a running pipeline status by itself as proof that the data arrived. The order and embedded-shipment counts are the quickstart's success condition.

If a setup command fails, the script prints the CLI diagnostic and exits. It does not continue to the snapshot check or report an empty target as success.

3. Inspect one assembled order

Change to the generated directory and start the bundled CLI:

cd tapstate-demo
./tapstate -w work

At the prompt, connect and sign in:

connect http://127.0.0.1:8080
login admin

Enter the password stored in the local .env file. Then run:

show collections
views.order_state.find({id:1})
status order_pipeline

For the published seed data, the first query returns this business shape (MongoDB's generated _id is omitted):

{
  id: 1,
  customer: "alice",
  amount: Decimal128("10.00"),
  shipments: [
    { id: 1, order_id: 1, carrier: "dhl", status: "delivered" },
    { id: 2, order_id: 1, carrier: "ups", status: "in_transit" }
  ]
}

The order fields come from MySQL, while the shipments array comes from PostgreSQL. You have now completed the shortest runnable tapstate path.

Next steps

• Explore the order-state demo to change both source databases and watch the document stay current.
• Install the CLI when you want tapstate available outside the playground.
• Create your own workspace to author and validate resources for systems your tapstate environment can reach.
• Use Troubleshooting if the success line or assembled document does not appear.

Keep, stop, or remove the playground

Keep the playground running while you explore the order-state demo or prepare a workspace for your own MySQL or PostgreSQL source. Confirm that the tapstate server can reach the database before applying it. This remains a disposable evaluation environment; use sample or non-sensitive data only.

To pause it and preserve the sample data for later, run this from tapstate-demo:

docker compose stop

Resume the same environment later with docker compose start.

When you no longer need the playground, remove its container data and start clean next time:

docker compose down -v

This permanently removes the sample MySQL, PostgreSQL, and MongoDB volumes. It does not remove the files or downloaded images.