sqt playground

sqt playground creates a ready-made orders project and starts its services on your machine with Docker. Then the ordinary sqt plan, sqt build and sqt deployment commands work from the project directory with no connection flags.

sqt playground
cd sqltide-playground
sqt build
sqt deployment promote --latest
sqt playground query consumer.sql

The project’s README.md walks through changing a model, building the new version beside the published one, comparing the two and promoting it.

Starting the services, query, up, down and --latest are available from SQLTide 0.68.0. Earlier versions only copy the project.

Templates

Template	Local services	What it shows
basic (default)	ClickHouse	One model over a seeded orders table. The new version keeps only completed orders; the consumer query returns different rows once you promote it.
streaming	Redpanda, ClickHouse and an order producer	Order events flow from a three-partition Redpanda topic through ClickHouse’s Kafka engine into four models with SQL tests, audits and a console sensor. The new version adds a net revenue column, rebuilt from retained history while live events keep arriving.

Both templates use virtual mode: building never changes what consumers read until you run sqt deployment promote. See staged deployments.

Commands

Command	What it does
sqt playground [DIRECTORY]	Create the project and start its services. DIRECTORY defaults to sqltide-playground, or sqltide-streaming-playground with --template streaming
sqt playground query FILE	Run each statement in a SQL file against the playground and print the results
sqt playground up	Start the services again
sqt playground down	Stop the services and keep their data

query, up and down run in the project directory, or take --project-dir.

Options

Option	Purpose
--template basic|streaming	Project to create; defaults to basic
--no-start	Only create the project; start it later with sqt playground up
--candidate	query: read the newest unpublished deployment instead of what consumers read
--compare	query: print what consumers read, then the newest unpublished deployment
--volumes	down: also delete the playground’s data

--candidate and --compare replace each stable name the deployment changed, such as tbl__order_report, with that deployment’s own table. They read nothing else differently.

The destination must not exist. sqt playground never overwrites a file or directory; to start over, create a new playground in a new directory. If Docker is not running, the project is still created, and the command exits with status 1 and says to run sqt playground up once Docker is available. Use --no-start in scripts that only need the files.

Requirements

• SQLTide with Python 3.12 or newer.
• Docker Engine or Docker Desktop with Compose v2. The first start downloads ClickHouse and, for streaming, Redpanda and a Python base image.
• Free loopback ports: 18124 for basic; 18125 and 19092 for streaming. Services bind to 127.0.0.1 only.

Each project’s credentials are public values for its own containers, and its sqltide_project.toml sets environment = false so SQLTIDE_CLICKHOUSE_* variables cannot point it at another warehouse.