sqlbuild 0.21.0__tar.gz → 0.22.1__tar.gz

sqlbuild-0.22.1/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.22.1"
+}

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.22.1](https://github.com/chio-labs/sqlbuild/compare/v0.22.0...v0.22.1) (2026-05-28)
+
+
+### Bug Fixes
+
+* gate virtual operations on state status ([a89f806](https://github.com/chio-labs/sqlbuild/commit/a89f8063a04c54174e67dcd0f812dae968cd01f1))
+* gate virtual operations on state status ([c2edad2](https://github.com/chio-labs/sqlbuild/commit/c2edad2c79a9e3806d3294b234f35676271a03b8))
+
+## [0.22.0](https://github.com/chio-labs/sqlbuild/compare/v0.21.0...v0.22.0) (2026-05-28)
+
+
+### Features
+
+* add virtual playground template ([9aa01a4](https://github.com/chio-labs/sqlbuild/commit/9aa01a4d292faaf75059bb25aa4771eae5a7c948))
+* add virtual playground template ([a4ce508](https://github.com/chio-labs/sqlbuild/commit/a4ce5088f62ea1ebe0f6077ebdfc8357f2edbf06))
+
 ## [0.21.0](https://github.com/chio-labs/sqlbuild/compare/v0.20.1...v0.21.0) (2026-05-28)
 
 

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.21.0
+Version: 0.22.1
 Summary: Typed, test-first SQL pipelines with local E2E testing
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -58,7 +58,7 @@ SQLBuild is a SQL pipeline framework that validates SQL at compile time, blocks
 ```bash
 pip install sqlbuild
 # or
-uv add sqlbuild
+uv pip install sqlbuild
 ```
 
 Create and run the playground project:

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/README.md

@@ -29,7 +29,7 @@ SQLBuild is a SQL pipeline framework that validates SQL at compile time, blocks
 ```bash
 pip install sqlbuild
 # or
-uv add sqlbuild
+uv pip install sqlbuild
 ```
 
 Create and run the playground project:

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlbuild"
-version = "0.21.0"
+version = "0.22.1"
 description = "Typed, test-first SQL pipelines with local E2E testing"
 readme = "README.md"
 requires-python = ">=3.12"

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/src/sqlbuild/cli/commands/main/diff.py

@@ -219,7 +219,15 @@ def _run_virtual_diff_cli(
         stream=sys.stdout,
         use_color=use_color,
     )
-    result, selected_names, skipped_names, from_stale, to_stale = run_virtual_diff(
+    (
+        result,
+        selected_names,
+        skipped_names,
+        from_stale,
+        to_stale,
+        from_working,
+        to_working,
+    ) = run_virtual_diff(
         project_dir=project_dir,
         discovered_inputs=discovered_inputs,
         adapter=adapter,
@@ -255,6 +263,8 @@ def _run_virtual_diff_cli(
         skipped_names=skipped_names,
         from_stale=from_stale,
         to_stale=to_stale,
+        from_working=from_working,
+        to_working=to_working,
         allow_partial_diff=allow_partial_diff,
         verbose=verbose,
         use_color=use_color,

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/src/sqlbuild/cli/commands/main/helpers/diff/virtual_output.py

@@ -13,6 +13,8 @@ def format_virtual_diff_header(
     skipped_names: tuple[str, ...],
     from_stale: tuple[str, ...],
     to_stale: tuple[str, ...],
+    from_working: bool,
+    to_working: bool,
     allow_partial_diff: bool,
     verbose: bool,
     use_color: bool,
@@ -27,8 +29,9 @@ def format_virtual_diff_header(
         len(selected_names) - len(skipped_names), use_color=use_color
     )
     skipped_count: str = _format_skipped_count(len(skipped_names), use_color=use_color)
-    working_label: str = "yes" if from_stale or to_stale else "no"
-    if from_stale or to_stale:
+    has_working_vde: bool = from_working or to_working
+    working_label: str = "yes" if has_working_vde else "no"
+    if has_working_vde:
         working_value: str = yellow_bold(working_label) if use_color else working_label
         if allow_partial_diff:
             suffix: str = dim(" (partial allowed)") if use_color else " (partial allowed)"

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/src/sqlbuild/cli/commands/main/helpers/playground/constants.py

@@ -4,4 +4,5 @@ PLAYGROUND_TEMPLATE_VALUES: tuple[str, ...] = (
     "waffle_shop",
     "loader_waffle_shop",
     "dagster",
+    "virtual",
 )

sqlbuild-0.22.1/src/sqlbuild/cli/commands/main/helpers/playground/copy.py

@@ -0,0 +1,388 @@
+"""Copy packaged playground templates to user projects."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from sqlbuild.cli.commands.main.helpers.playground.constants import PLAYGROUND_TEMPLATE_VALUES
+from sqlbuild.cli.commands.main.shared.exceptions import CliUserError
+
+_TEMPLATE_PACKAGE: str = "sqlbuild.playground"
+_WAFFLE_SHOP_TEMPLATE: str = "templates/waffle_shop"
+_LOADER_WAFFLE_SHOP_TEMPLATE: str = "templates/loader_waffle_shop"
+
+_VIRTUAL_PROJECT_TOML: str = """name = "loader_waffle_shop_virtual"
+adapter = "duckdb"
+environment_mode = "virtual"
+default_environment = "dev"
+
+[connection]
+database = "loader_waffle_shop_virtual.duckdb"
+
+[settings]
+default_audit_severity = "warn"
+
+[defaults]
+materialized = "table"
+
+[environments.dev]
+schema = "dev"
+defer_sources_to = "dev"
+
+[environments.dev.state]
+backend = "duckdb"
+schema = "sqlbuild_state"
+unsuffixed_virtual_env = "dev"
+allow_reset = true
+
+[environments.dev.state.connection]
+database = "loader_waffle_shop_state.duckdb"
+"""
+
+_VIRTUAL_FACT_WAFFLE_ORDERS_SQL: str = """MODEL (
+  materialized table,
+  columns (
+    order_id (nullable false, audits [not_null, unique]),
+    revenue_cents (nullable false, audits [not_null]),
+  ),
+);
+
+SELECT
+  o.order_id,
+  o.customer_id,
+  c.plan_name,
+  o.waffle_type,
+  p.waffle_category,
+  o.quantity,
+  o.price_cents,
+  o.quantity * o.price_cents AS revenue_cents,
+  o.load_seq
+FROM __source("raw_orders") o
+LEFT JOIN __source("raw_customers") c ON o.customer_id = c.customer_id
+LEFT JOIN __seed("waffle_price_tiers") p ON o.waffle_type = p.waffle_type
+"""
+
+_VIRTUAL_TEST_FACT_WAFFLE_ORDERS_SQL: str = """TEST();
+
+WITH
+__source__raw_orders AS (
+  SELECT
+    1 AS order_id,
+    10 AS customer_id,
+    'classic' AS waffle_type,
+    2 AS quantity,
+    600 AS price_cents,
+    1 AS load_seq
+),
+__source__raw_customers AS (
+  SELECT
+    10 AS customer_id,
+    'plus' AS plan_name,
+    1 AS load_seq
+),
+__seed__waffle_price_tiers AS (
+  SELECT 'classic' AS waffle_type, 'standard' AS waffle_category
+),
+__expected__fact_waffle_orders AS (
+  SELECT
+    1 AS order_id,
+    10 AS customer_id,
+    'plus' AS plan_name,
+    'classic' AS waffle_type,
+    'standard' AS waffle_category,
+    2 AS quantity,
+    600 AS price_cents,
+    1200 AS revenue_cents,
+    1 AS load_seq
+),
+__assert__revenue_is_non_negative AS (
+  SELECT *
+  FROM __ref("fact_waffle_orders")
+  WHERE revenue_cents < 0
+)
+SELECT 1
+"""
+
+_VIRTUAL_SCENARIO_CUSTOMER_REVENUE_SQL: str = """SCENARIO (
+  description: "Customer revenue includes seed-backed waffle categories",
+  tags: ["virtual", "example"]
+);
+
+WITH
+__source__raw_orders AS (
+  SELECT
+    1 AS order_id,
+    10 AS customer_id,
+    'classic' AS waffle_type,
+    2 AS quantity,
+    600 AS price_cents,
+    1 AS load_seq
+  UNION ALL
+  SELECT
+    2 AS order_id,
+    10 AS customer_id,
+    'blueberry' AS waffle_type,
+    1 AS quantity,
+    750 AS price_cents,
+    1 AS load_seq
+),
+__source__raw_customers AS (
+  SELECT
+    10 AS customer_id,
+    'plus' AS plan_name,
+    1 AS load_seq
+),
+__seed__waffle_price_tiers AS (
+  SELECT 'classic' AS waffle_type, 'standard' AS waffle_category
+  UNION ALL
+  SELECT 'blueberry' AS waffle_type, 'fruit' AS waffle_category
+),
+__expected__customer_revenue AS (
+  SELECT
+    10 AS customer_id,
+    'plus' AS plan_name,
+    1950 AS revenue_cents,
+    2 AS order_count
+),
+__assert__no_negative_customer_revenue AS (
+  SELECT *
+  FROM __ref("customer_revenue")
+  WHERE revenue_cents < 0
+)
+SELECT 1
+"""
+
+_VIRTUAL_SEED_SCHEMA_YML: str = """seeds:
+  - name: waffle_price_tiers
+    description: Waffle category lookup used by the virtual playground.
+    columns:
+      - name: waffle_type
+        type: VARCHAR
+      - name: waffle_category
+        type: VARCHAR
+"""
+
+_VIRTUAL_SEED_CSV: str = """waffle_type,waffle_category
+classic,standard
+blueberry,fruit
+chocolate,dessert
+"""
+
+_VIRTUAL_README: str = """# SQLBuild Virtual Environments Playground
+
+This project is a local DuckDB playground for SQLBuild virtual environments. It is
+self-contained and does not require warehouse credentials.
+
+Virtual environments are an advanced, state-backed workflow. This playground uses a
+local DuckDB state database so you can try the lifecycle without operating shared
+infrastructure.
+
+## Try It
+
+Initialize the state store:
+
+```bash
+sqb state init
+```
+
+Build the default `dev` virtual environment:
+
+```bash
+sqb build
+```
+
+Create a branch-like virtual environment:
+
+```bash
+sqb build --virtual-env pr
+```
+
+Modify a model, then rebuild only the branch:
+
+```bash
+sqb build --virtual-env pr
+```
+
+Run the project checks:
+
+```bash
+sqb test
+sqb audit
+sqb scenario test
+```
+
+Compare the branch with `dev`:
+
+```bash
+sqb diff dev:pr --schema-only
+```
+
+Promote the branch into `dev`:
+
+```bash
+sqb promote --from pr --to dev
+```
+
+Inspect and roll back checkpoints:
+
+```bash
+sqb state checkpoints list --virtual-env dev
+sqb rollback --virtual-env dev
+```
+
+## What This Shows
+
+- DuckDB-backed local virtual environment execution
+- A local DuckDB state store
+- Branch-like virtual environments with `--virtual-env`
+- Low-copy promotion through versioned pointers and logical views
+- Checkpoint-backed rollback
+- Loader-backed waffle shop models without external services
+- A seed lookup that is loaded before virtual model execution
+- Unit test, audit, and scenario commands that exercise the generated project
+"""
+
+_DAGSTER_DEFINITIONS: str = '''"""Dagster definitions for the SQLBuild waffle shop playground."""
+
+from pathlib import Path
+
+import dagster as dg
+
+from sqlbuild.integrations.dagster import (
+    SqlBuildCliResource,
+    SqlBuildProject,
+    sqlbuild_assets,
+    sqlbuild_scenario_checks,
+)
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+SQLBUILD_PROJECT = SqlBuildProject(project_dir=PROJECT_DIR)
+
+SQLBUILD_PROJECT.prepare_if_dev()
+
+
+@sqlbuild_assets(
+    project=SQLBUILD_PROJECT,
+    required_resource_keys={"sqb"},
+    include_scenario_checks=False,
+)
+def waffle_shop_assets(context: dg.AssetExecutionContext):
+    yield from context.resources.sqb.cli(["build"], context=context).stream()
+
+
+@sqlbuild_scenario_checks(
+    project=SQLBUILD_PROJECT,
+    required_resource_keys={"sqb"},
+)
+def waffle_shop_scenarios(context: dg.AssetCheckExecutionContext):
+    yield from context.resources.sqb.cli(["scenario", "test"], context=context).stream()
+
+
+defs = dg.Definitions(
+    assets=[waffle_shop_assets],
+    asset_checks=[waffle_shop_scenarios],
+    resources={"sqb": SqlBuildCliResource(project_dir=SQLBUILD_PROJECT)},
+)
+'''
+
+_DAGSTER_README: str = """# SQLBuild + Dagster playground
+
+This directory contains a Dagster definitions file for the generated SQLBuild waffle shop project.
+
+## Run Dagster
+
+Install SQLBuild with the Dagster extra, then start Dagster from the project root:
+
+```bash
+uv add "sqlbuild[dagster]"
+DAGSTER_IS_DEV_CLI=1 uv run dagster dev -f dagster/definitions.py
+```
+
+Open the Dagster UI, materialize the `waffle_shop_assets` asset group, then run the scenario checks.
+
+The definitions use `SqlBuildProject.prepare_if_dev()` to generate `target/sqlbuild_dag.json`
+when Dagster starts in dev mode.
+"""
+
+
+def create_playground_project(*, target_dir: Path, template: str = "waffle_shop") -> None:
+    """Create a DuckDB-backed waffle shop playground project."""
+
+    if target_dir.exists():
+        raise CliUserError(
+            f"playground target already exists: {target_dir}",
+            code="C701",
+            help="choose a new directory or remove the existing one",
+        )
+    if template not in PLAYGROUND_TEMPLATE_VALUES:
+        raise CliUserError(
+            f"unknown playground template: {template}",
+            code="C703",
+            help=f"choose one of: {', '.join(PLAYGROUND_TEMPLATE_VALUES)}",
+        )
+
+    template_path: str = (
+        _LOADER_WAFFLE_SHOP_TEMPLATE
+        if template in ("loader_waffle_shop", "virtual")
+        else _WAFFLE_SHOP_TEMPLATE
+    )
+    template_root: Traversable = files(_TEMPLATE_PACKAGE).joinpath(template_path)
+    if not template_root.is_dir():
+        raise CliUserError(
+            "packaged playground template is missing",
+            code="C702",
+            help="reinstall SQLBuild or report a packaging issue",
+        )
+    _copy_tree(source=template_root, target=target_dir)
+    if template == "dagster":
+        _write_dagster_template_files(target_dir=target_dir)
+    if template == "virtual":
+        _write_virtual_template_files(target_dir=target_dir)
+
+
+def _copy_tree(*, source: Traversable, target: Path) -> None:
+    target.mkdir(parents=True, exist_ok=False)
+    child: Traversable
+    for child in source.iterdir():
+        child_target: Path = target / _generated_name(child.name)
+        if child.is_dir():
+            _copy_tree(source=child, target=child_target)
+            continue
+        child_target.write_bytes(child.read_bytes())
+
+
+def _generated_name(template_name: str) -> str:
+    if template_name.endswith(".py.txt"):
+        return template_name.removesuffix(".txt")
+    return template_name
+
+
+def _write_dagster_template_files(*, target_dir: Path) -> None:
+    dagster_dir: Path = target_dir / "dagster"
+    dagster_dir.mkdir()
+    (dagster_dir / "definitions.py").write_text(_DAGSTER_DEFINITIONS, encoding="utf-8")
+    (dagster_dir / "README.md").write_text(_DAGSTER_README, encoding="utf-8")
+
+
+def _write_virtual_template_files(*, target_dir: Path) -> None:
+    (target_dir / "sqlbuild_project.toml").write_text(_VIRTUAL_PROJECT_TOML, encoding="utf-8")
+    (target_dir / "README.md").write_text(_VIRTUAL_README, encoding="utf-8")
+    (target_dir / "models/fact_waffle_orders.sql").write_text(
+        _VIRTUAL_FACT_WAFFLE_ORDERS_SQL, encoding="utf-8"
+    )
+    seeds_dir: Path = target_dir / "seeds"
+    seeds_dir.mkdir()
+    (seeds_dir / "lookups.yml").write_text(_VIRTUAL_SEED_SCHEMA_YML, encoding="utf-8")
+    (seeds_dir / "waffle_price_tiers.csv").write_text(_VIRTUAL_SEED_CSV, encoding="utf-8")
+    unit_tests_dir: Path = target_dir / "tests" / "unit"
+    unit_tests_dir.mkdir(parents=True)
+    (unit_tests_dir / "test_fact_waffle_orders.sql").write_text(
+        _VIRTUAL_TEST_FACT_WAFFLE_ORDERS_SQL, encoding="utf-8"
+    )
+    scenarios_dir: Path = target_dir / "tests" / "scenarios"
+    scenarios_dir.mkdir(parents=True)
+    (scenarios_dir / "customer_revenue_minimal.sql").write_text(
+        _VIRTUAL_SCENARIO_CUSTOMER_REVENUE_SQL, encoding="utf-8"
+    )

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/src/sqlbuild/cli/commands/main/playground.py

@@ -39,6 +39,8 @@ def run_playground(
     example_name: str = (
         "waffle shop + Dagster"
         if template == "dagster"
+        else "virtual environments waffle shop"
+        if template == "virtual"
         else "loader-focused waffle shop"
         if template == "loader_waffle_shop"
         else "waffle shop"
@@ -47,10 +49,20 @@ def run_playground(
     print()
     print(f"{try_label}:")
     print(f"{command_prefix}cd {display_path}")
-    print(f"{command_prefix}sqb compile")
-    print(f"{command_prefix}sqb build")
-    print(f"{command_prefix}sqb test")
-    print(f"{command_prefix}sqb audit")
+    if template == "virtual":
+        print(f"{command_prefix}sqb state init")
+        print(f"{command_prefix}sqb build")
+        print(f"{command_prefix}sqb build --virtual-env pr")
+        print(f"{command_prefix}sqb test")
+        print(f"{command_prefix}sqb audit")
+        print(f"{command_prefix}sqb scenario test")
+        print(f"{command_prefix}sqb diff dev:pr --schema-only")
+        print(f"{command_prefix}sqb promote --from pr --to dev")
+    else:
+        print(f"{command_prefix}sqb compile")
+        print(f"{command_prefix}sqb build")
+        print(f"{command_prefix}sqb test")
+        print(f"{command_prefix}sqb audit")
     if template == "dagster":
         print(f"{command_prefix}DAGSTER_IS_DEV_CLI=1 dagster dev -f dagster/definitions.py")
     return 0

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/src/sqlbuild/virtual/diff/helpers/diff.py

@@ -15,7 +15,12 @@ from sqlbuild.compiler.pipeline.models import ProjectGraph
 from sqlbuild.compiler.planner.main.selection import resolve_project_selectors
 from sqlbuild.virtual.executor.main.rewrite import rewrite_virtual_project_model_targets
 from sqlbuild.virtual.planner.main.targets import build_virtual_target_from_physical_relation
-from sqlbuild.virtual.state.models import PhysicalRelationRecord, VirtualEnvironmentRefRecord
+from sqlbuild.virtual.state.models import (
+    PhysicalRelationRecord,
+    VirtualEnvironmentRecord,
+    VirtualEnvironmentRefRecord,
+)
+from sqlbuild.virtual.state.types import VirtualEnvironmentStatus
 
 
 def resolve_virtual_diff_model_names(
@@ -98,3 +103,17 @@ def rewrite_project_to_physical_relations(
         if model.name in relations
     }
     return rewrite_virtual_project_model_targets(project=project, rewritten_targets=targets)
+
+
+def non_finalized_environment_names(
+    environments: tuple[tuple[str, VirtualEnvironmentRecord | None], ...],
+) -> tuple[str, ...]:
+    return tuple(
+        name
+        for name, environment in environments
+        if environment is None or environment.status != VirtualEnvironmentStatus.FINALIZED
+    )
+
+
+def is_working_environment(environment: VirtualEnvironmentRecord | None) -> bool:
+    return environment is None or environment.status != VirtualEnvironmentStatus.FINALIZED

{sqlbuild-0.21.0 → sqlbuild-0.22.1}/src/sqlbuild/virtual/diff/main/diff.py

@@ -18,6 +18,8 @@ from sqlbuild.executor.diff.models import DiffExecutionResult
 from sqlbuild.shared.types import ExternalSqlReferenceResolver
 from sqlbuild.virtual.diff.helpers.diff import (
     filter_models_with_changed_virtual_refs,
+    is_working_environment,
+    non_finalized_environment_names,
     read_physical_relations_for_refs,
     resolve_virtual_diff_model_names,
     rewrite_project_to_physical_relations,
@@ -28,6 +30,7 @@ from sqlbuild.virtual.state.main.runtime import build_state_runtime
 from sqlbuild.virtual.state.models import (
     ModelVersionRecord,
     PhysicalRelationRecord,
+    VirtualEnvironmentRecord,
     VirtualEnvironmentRefRecord,
 )
 
@@ -61,6 +64,8 @@ def run_virtual_diff(
     tuple[str, ...],
     tuple[str, ...],
     tuple[str, ...],
+    bool,
+    bool,
 ]:
     """Run a diff between two VDEs in the active physical environment."""
 
@@ -92,6 +97,16 @@ def run_virtual_diff(
         inspect_start: float = time.perf_counter()
         if on_progress is not None:
             on_progress("Inspecting virtual state...")
+        from_environment: VirtualEnvironmentRecord | None = backend.get_virtual_environment(
+            state_connection,
+            schema=config.schema,
+            virtual_environment_name=from_virtual_environment_name,
+        )
+        to_environment: VirtualEnvironmentRecord | None = backend.get_virtual_environment(
+            state_connection,
+            schema=config.schema,
+            virtual_environment_name=to_virtual_environment_name,
+        )
         from_refs: tuple[VirtualEnvironmentRefRecord, ...] = backend.get_virtual_environment_refs(
             state_connection,
             schema=config.schema,
@@ -135,13 +150,16 @@ def run_virtual_diff(
             bound_model_versions=to_model_versions,
         )
         if not select and not allow_partial_diff:
-            stale: tuple[str, ...] = tuple(
-                sorted({*from_semantics.stale_model_names, *to_semantics.stale_model_names})
+            non_finalized: tuple[str, ...] = non_finalized_environment_names(
+                (
+                    (from_virtual_environment_name, from_environment),
+                    (to_virtual_environment_name, to_environment),
+                )
             )
-            if stale:
+            if non_finalized:
                 raise PlannerInputError(
-                    "whole-VDE virtual diff requires finalized VDEs; stale models: "
-                    + ", ".join(stale),
+                    "whole-VDE virtual diff requires finalized VDEs; non-finalized VDEs: "
+                    + ", ".join(non_finalized),
                     code="S012",
                     help="Re-run with --allow-partial-diff to inspect a working VDE.",
                 )
@@ -185,6 +203,8 @@ def run_virtual_diff(
             skipped_names,
             from_semantics.stale_model_names,
             to_semantics.stale_model_names,
+            is_working_environment(from_environment),
+            is_working_environment(to_environment),
         )
 
     left_project: CompiledProject = rewrite_project_to_physical_relations(
@@ -230,6 +250,8 @@ def run_virtual_diff(
         skipped_names,
         from_semantics.stale_model_names,
         to_semantics.stale_model_names,
+        is_working_environment(from_environment),
+        is_working_environment(to_environment),
     )