Skip to main content

​
sqb playground

Creates a self-contained waffle shop project with DuckDB. No warehouse credentials, no git clone, no external data - just a working project you can compile, build, test, and explore immediately.

​
Usage

sqb playground [name]
The positional argument is the directory to create (default sqlbuild-playground). The template is chosen with --template (default waffle_shop).

​
Templates

TemplateDescription
waffle_shopDefault. DuckDB-backed project with models, tests, scenarios, and macros.
dagsterWaffle shop project plus a dagster/ directory with a ready-to-run definitions.py.
riversWaffle shop project plus a rivers_pipeline/ directory with a Rivers repository definition.
virtualWaffle shop with virtual environments enabled, a local DuckDB state store, loaders, and the full virtual lifecycle (build, promote, rollback).
python_nodesA small DuckDB project demonstrating Python nodes: a task feeding a loader, a model read by a Python asset through ctx.relation(model(...)), a soft-skip fan-in, materialized=False, and a Python check.

​
What it creates

A complete DuckDB-backed project with:
  • Staging views, fact/dimension tables, and incremental models
  • Sources with inline expression data (no external setup)
  • Seeds, SQL functions, and a custom materialization
  • Built-in and custom audits
  • SQL unit tests including chain tests
  • E2E scenario tests
  • Python macros
  • AI agent skill files (auto-installed for OpenCode, Claude Code, and other agents)
The dagster template adds:
  • dagster/definitions.py - Dagster definitions with sqlbuild_assets, sqlbuild_scenario_checks, and SqlBuildCliResource
  • dagster/README.md - Setup instructions
The python_nodes template instead creates a focused Python-nodes project:
  • tasks/orders.py, loaders/orders.py, assets/orders_export.py, checks/orders_export.py
  • A fact_orders SQL model over a managed raw_orders source
  • Examples of the SQL boundary, ctx.relation(model(...)), soft-skip fan-in, and a Python check

​
Examples

# Default waffle shop
sqb playground waffle-shop
cd waffle-shop
sqb build

# With Dagster integration
sqb playground --template dagster
cd sqlbuild-playground
uv pip install 'sqlbuild[dagster]'
dagster dev -f dagster/definitions.py

# With Rivers integration
sqb playground --template rivers
cd sqlbuild-playground
uv pip install 'sqlbuild[rivers]'
uv run rivers dev rivers_pipeline.definitions

# With virtual environments
sqb playground --template virtual
cd sqlbuild-playground
sqb state init
sqb build
sqb build --virtual-env pr
sqb promote --from pr --to dev

# With Python nodes
sqb playground --template python_nodes
cd sqlbuild-playground
sqb build --select +fact_orders --select +orders_export
sqb check --select +check_orders_export

​
Notes

  • The target directory must not already exist
  • DuckDB is included as a core dependency - no extra installation needed
  • The local DuckDB database file is created on the first build
  • The Dagster template uses prepare_if_dev() to auto-generate the DAG artifact when Dagster starts in dev mode