Skip to content
by SQLStack
Docs
Demo

Getting started

Quickstart

Install SQLTide, start the playground, and promote a changed model without changing the query consumers run.

In this guide you install SQLTide, start a small orders project on your machine, change one of its SQL models, and switch the view your query reads to the new version. It takes about ten minutes. sqt playground sets up the project and runs ClickHouse for it in Docker.

Only want to look around? The UI demo runs in your browser with nothing to install.

Prerequisites

Section titled “Prerequisites”
  • Python 3.12 or newer
  • Docker with Compose v2, running
  • Port 18124 free on your machine

1. Install SQLTide

Section titled “1. Install SQLTide”
pip install --upgrade sqltide

The commands in this guide need SQLTide 0.68 or newer; sqt --version prints yours.

2. Create the playground

Section titled “2. Create the playground”
sqt playground
cd sqltide-playground

sqt playground creates the project, starts ClickHouse and loads three orders. The project builds one model, pipelines/pl__orders/order_report.sql. Consumers query its stable name, tbl__order_report, as consumer.sql does.

3. Publish the first version

Section titled “3. Publish the first version”
sqt build
sqt deployment promote --latest
sqt playground query consumer.sql

sqt build shows what it will create and asks you to confirm; type y. The build creates a new deployment that consumers cannot see yet. Promoting it points tbl__order_report at it, and the query returns orders 1, 2 and 3.

4. Build a changed version beside it

Section titled “4. Build a changed version beside it”
cp revisions/completed_orders.sql pipelines/pl__orders/order_report.sql
sqt build
sqt playground query consumer.sql --compare

The new version keeps only completed orders. --compare runs the query against what consumers read and against the new, unpublished build: consumers still get orders 1, 2 and 3, and the new version returns 1 and 3.

5. Promote

Section titled “5. Promote”
sqt deployment promote --latest
sqt playground query consumer.sql

The same query now returns orders 1 and 3. The first version stays in ClickHouse, so sqt deployment rollback --previous switches back to it.

6. Clean up

Section titled “6. Clean up”
sqt playground down --volumes

This stops ClickHouse and deletes the playground’s data. Without --volumes it keeps the data, and sqt playground up starts it again.

Next steps

Section titled “Next steps”
Part of SQLStack