sqlbuild 0.27.0__tar.gz → 0.28.0__tar.gz

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

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

{sqlbuild-0.27.0 → sqlbuild-0.28.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.28.0](https://github.com/chio-labs/sqlbuild/compare/v0.27.0...v0.28.0) (2026-06-06)
+
+
+### Features
+
+* add source freshness command ([a2d543d](https://github.com/chio-labs/sqlbuild/commit/a2d543d4efeab7df472c7d02385c7a75a6fa116f))
+* add source freshness state comparison ([77c70d9](https://github.com/chio-labs/sqlbuild/commit/77c70d90310ca399f346a8390089a7b0cf540b55))
+
+
+### Bug Fixes
+
+* place provider default target at top level ([a861c03](https://github.com/chio-labs/sqlbuild/commit/a861c03cf263db723f16d1ae1f2447805d23a588))
+
 ## [0.27.0](https://github.com/chio-labs/sqlbuild/compare/v0.26.2...v0.27.0) (2026-06-03)
 
 

{sqlbuild-0.27.0 → sqlbuild-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.27.0
+Version: 0.28.0
 Summary: Typed, test-first SQL pipelines with local E2E testing
 License-File: LICENSE
 Requires-Python: >=3.12

{sqlbuild-0.27.0 → sqlbuild-0.28.0}/pyproject.toml

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

{sqlbuild-0.27.0 → sqlbuild-0.28.0}/src/sqlbuild/cli/commands/main/entry.py

@@ -145,6 +145,18 @@ def _build_parser(*, use_color: bool = False) -> argparse.ArgumentParser:
     add_vars_args(run_parser)
     add_dbt_config_args(run_parser)
 
+    freshness_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.FRESHNESS)
+    freshness_parser.add_argument("--no-sql-validation", action="store_true", default=False)
+    freshness_parser.add_argument("--json", action="store_true", default=False)
+    freshness_parser.add_argument("--state", action="store_true", default=False)
+    freshness_parser.add_argument("--virtual-env", default=None)
+    freshness_parser.add_argument("--fail-on-error", action="store_true", default=False)
+    freshness_parser.add_argument("--fail-on-stale", action="store_true", default=False)
+    add_execution_json_output_arg(freshness_parser)
+    add_select_args(freshness_parser)
+    add_vars_args(freshness_parser)
+    add_dbt_config_args(freshness_parser)
+
     test_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.TEST)
     test_parser.add_argument("--no-sql-validation", action="store_true", default=False)
     test_parser.add_argument("--json", action="store_true", default=False)
@@ -403,6 +415,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     from sqlbuild.cli.commands.main.dbt import run_dbt_command
     from sqlbuild.cli.commands.main.debug import run_debug
     from sqlbuild.cli.commands.main.diff import run_diff
+    from sqlbuild.cli.commands.main.freshness import run_freshness
     from sqlbuild.cli.commands.main.helpers.scenario.capture import run_scenario_capture
     from sqlbuild.cli.commands.main.init import run_init
     from sqlbuild.cli.commands.main.janitor import run_janitor
@@ -457,6 +470,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         ),
         run_build=run_build,
         run_run=run_run,
+        run_freshness=run_freshness,
         run_test=run_test,
         run_check=run_check,
         run_audit=run_audit,
@@ -643,6 +657,21 @@ def _main_with_dependencies(
                 args.json,
                 args.json_output,
             )
+        if args.command == CliCommand.FRESHNESS:
+            return handlers.run_freshness(
+                project_dir,
+                args.no_sql_validation,
+                args.no_color,
+                select,
+                tuple(args.exclude),
+                args.vars,
+                args.json,
+                args.json_output,
+                args.fail_on_error,
+                args.state,
+                args.fail_on_stale,
+                args.virtual_env,
+            )
         if args.command == CliCommand.TEST:
             return handlers.run_test(
                 project_dir,

sqlbuild-0.28.0/src/sqlbuild/cli/commands/main/freshness.py

@@ -0,0 +1,133 @@
+"""CLI source freshness command entry point."""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from sqlbuild.adapter.base.base_adapter import BaseAdapter
+from sqlbuild.cli.commands.main.helpers.freshness.models import FreshnessCommandResult
+from sqlbuild.cli.commands.main.helpers.freshness.observe import (
+    observe_source_freshness_for_command,
+)
+from sqlbuild.cli.commands.main.helpers.freshness.output import (
+    format_freshness_json,
+    format_freshness_text,
+)
+from sqlbuild.cli.commands.main.helpers.freshness.selection import resolve_freshness_source_names
+from sqlbuild.cli.commands.main.helpers.freshness.state import (
+    read_direct_freshness_state_for_command,
+    read_virtual_freshness_state_for_command,
+)
+from sqlbuild.cli.commands.main.shared.exceptions import CliUserError
+from sqlbuild.cli.commands.main.shared.helpers.adapters import resolve_adapter
+from sqlbuild.cli.commands.main.shared.helpers.connection import resolve_project_connection_config
+from sqlbuild.cli.commands.main.shared.helpers.execution_json import write_execution_json_output
+from sqlbuild.compiler.discovery.main.discover import discover_project_inputs
+from sqlbuild.compiler.discovery.models import DiscoveredProjectInputs
+from sqlbuild.compiler.pipeline.main.graph import build_project_graph
+from sqlbuild.compiler.pipeline.models import ProjectGraph
+from sqlbuild.compiler.source_freshness.models import SourceFreshnessIdentity, SourceFreshnessRecord
+from sqlbuild.spec.models.project import resolve_effective_adapter_name
+from sqlbuild.spec.models.source import SourceEntry
+
+
+def run_freshness(
+    project_dir: Path | None,
+    no_sql_validation: bool = False,
+    no_color: bool = False,
+    select: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    cli_vars: dict[str, object] | None = None,
+    json_output: bool = False,
+    json_output_path: Path | None = None,
+    fail_on_error: bool = False,
+    compare_state: bool = False,
+    fail_on_stale: bool = False,
+    virtual_environment_name: str | None = None,
+) -> int:
+    """Observe source freshness without writing state."""
+
+    del no_color
+    if fail_on_stale and not compare_state:
+        raise CliUserError("freshness --fail-on-stale requires --state", code="C238")
+    effective_project_dir: Path = project_dir if project_dir is not None else Path.cwd()
+    discovered_inputs: DiscoveredProjectInputs = discover_project_inputs(
+        project_dir=effective_project_dir
+    )
+    adapter_name: str = resolve_effective_adapter_name(
+        project_config=discovered_inputs.project_config,
+        local_config=discovered_inputs.local_config,
+    )
+    adapter: BaseAdapter = resolve_adapter(adapter_name, project_dir=effective_project_dir)
+    connection_config: dict[str, object] = resolve_project_connection_config(
+        discovered_inputs=discovered_inputs,
+        project_dir=effective_project_dir,
+        cli_vars=cli_vars,
+    )
+    graph: ProjectGraph = build_project_graph(
+        discovered_inputs=discovered_inputs,
+        adapter=adapter,
+        no_sql_validation=no_sql_validation,
+        cli_vars=cli_vars,
+    )
+    sources: tuple[SourceEntry, ...] = tuple(
+        source.source_entry for source in graph.project.sources
+    )
+    selected_source_names: tuple[str, ...] = resolve_freshness_source_names(
+        graph=graph,
+        select=select,
+        exclude=exclude,
+    )
+    if not selected_source_names:
+        result: FreshnessCommandResult = FreshnessCommandResult()
+    else:
+        connection: Any = adapter.connect(connection_config)
+        try:
+            previous_records_by_source_name: dict[str, SourceFreshnessRecord] | None = None
+            previous_records: dict[SourceFreshnessIdentity, SourceFreshnessRecord] | None = None
+            if compare_state and virtual_environment_name is not None:
+                previous_records_by_source_name = read_virtual_freshness_state_for_command(
+                    discovered_inputs=discovered_inputs,
+                    project_dir=effective_project_dir,
+                    virtual_environment_name=virtual_environment_name,
+                )
+            elif compare_state:
+                previous_records = read_direct_freshness_state_for_command(
+                    adapter=adapter,
+                    connection=connection,
+                    project=graph.project,
+                )
+            result = observe_source_freshness_for_command(
+                adapter=adapter,
+                connection=connection,
+                sources=sources,
+                select=selected_source_names,
+                exclude=(),
+                observed_at=datetime.now(),
+                previous_records=previous_records,
+                previous_records_by_source_name=previous_records_by_source_name,
+            )
+        finally:
+            adapter.close(connection)
+
+    payload: str = format_freshness_json(result)
+    if json_output:
+        write_execution_json_output(
+            payload=payload + "\n",
+            json_output=True,
+            json_output_path=json_output_path,
+        )
+    else:
+        if json_output_path is not None:
+            write_execution_json_output(
+                payload=payload + "\n",
+                json_output=False,
+                json_output_path=json_output_path,
+            )
+        sys.stdout.write(format_freshness_text(result))
+    if fail_on_stale and (result.changed_count or result.unknown_count or result.error_count):
+        return 1
+    return 1 if fail_on_error and (result.unknown_count or result.error_count) else 0

{sqlbuild-0.27.0 → sqlbuild-0.28.0}/src/sqlbuild/cli/commands/main/helpers/entry/models.py

@@ -76,6 +76,9 @@ class CliNamespace:
     lineage_depth: str = "all"
     lineage_mode: ColumnLineageMode = ColumnLineageMode.RICH
     no_connection: bool = False
+    fail_on_error: bool = False
+    fail_on_stale: bool = False
+    state: bool = False
     full: bool = False
     schema_only: bool = False
     allow_partial_diff: bool = False
@@ -210,6 +213,23 @@ class CliEntrypointHandlers:
         ],
         int,
     ]
+    run_freshness: Callable[
+        [
+            Path | None,
+            bool,
+            bool,
+            tuple[str, ...],
+            tuple[str, ...],
+            dict[str, object],
+            bool,
+            Path | None,
+            bool,
+            bool,
+            bool,
+            str | None,
+        ],
+        int,
+    ]
     run_test: Callable[
         [
             Path | None,

sqlbuild-0.28.0/src/sqlbuild/cli/commands/main/helpers/freshness/models.py

@@ -0,0 +1,55 @@
+"""Source freshness command models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sqlbuild.cli.commands.main.helpers.freshness.types import FreshnessSourceStatus
+
+
+@dataclass(frozen=True)
+class FreshnessSourceResult:
+    """Freshness observation result for one source."""
+
+    name: str
+    status: FreshnessSourceStatus
+    strategy: str | None = None
+    value_kind: str | None = None
+    current_data_version: str | None = None
+    previous_data_version: str | None = None
+    lag_tolerance: str | None = None
+    target_database: str | None = None
+    target_schema: str | None = None
+    target_name: str | None = None
+    message: str | None = None
+
+
+@dataclass(frozen=True)
+class FreshnessCommandResult:
+    """Source freshness command output payload."""
+
+    sources: tuple[FreshnessSourceResult, ...] = field(default_factory=tuple)
+
+    @property
+    def observed_count(self) -> int:
+        return sum(1 for source in self.sources if source.status == FreshnessSourceStatus.OBSERVED)
+
+    @property
+    def changed_count(self) -> int:
+        return sum(1 for source in self.sources if source.status == FreshnessSourceStatus.CHANGED)
+
+    @property
+    def unchanged_count(self) -> int:
+        return sum(1 for source in self.sources if source.status == FreshnessSourceStatus.UNCHANGED)
+
+    @property
+    def tolerated_count(self) -> int:
+        return sum(1 for source in self.sources if source.status == FreshnessSourceStatus.TOLERATED)
+
+    @property
+    def unknown_count(self) -> int:
+        return sum(1 for source in self.sources if source.status == FreshnessSourceStatus.UNKNOWN)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for source in self.sources if source.status == FreshnessSourceStatus.ERROR)

sqlbuild-0.28.0/src/sqlbuild/cli/commands/main/helpers/freshness/observe.py

@@ -0,0 +1,249 @@
+"""Source freshness command observation helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlbuild.adapter.strict.strict_adapter import StrictAdapter
+from sqlbuild.cli.commands.main.helpers.freshness.models import (
+    FreshnessCommandResult,
+    FreshnessSourceResult,
+)
+from sqlbuild.cli.commands.main.helpers.freshness.types import FreshnessSourceStatus
+from sqlbuild.compiler.source_freshness.main.data_version_hash import (
+    source_freshness_data_version_hash,
+)
+from sqlbuild.compiler.source_freshness.main.normalization import (
+    normalize_source_freshness_data_version,
+)
+from sqlbuild.compiler.source_freshness.main.observation import observe_configured_source_freshness
+from sqlbuild.compiler.source_freshness.main.record_equivalence import (
+    source_freshness_records_equivalent,
+)
+from sqlbuild.compiler.source_freshness.models import (
+    SourceFreshnessIdentity,
+    SourceFreshnessObservation,
+    SourceFreshnessRecord,
+)
+from sqlbuild.spec.models.source import SourceEntry, SourceFreshnessConfig
+from sqlbuild.spec.models.types import SourceFreshnessStrategy
+
+
+def observe_source_freshness_for_command(
+    *,
+    adapter: StrictAdapter,
+    connection: Any,
+    sources: tuple[SourceEntry, ...],
+    select: tuple[str, ...] = (),
+    exclude: tuple[str, ...] = (),
+    observed_at: datetime,
+    previous_records: dict[SourceFreshnessIdentity, SourceFreshnessRecord] | None = None,
+    previous_records_by_source_name: dict[str, SourceFreshnessRecord] | None = None,
+) -> FreshnessCommandResult:
+    """Observe current source freshness for the CLI command."""
+
+    selected_sources: tuple[SourceEntry, ...] = _selected_sources(
+        sources=sources,
+        select=select,
+        exclude=exclude,
+    )
+    results: list[FreshnessSourceResult] = []
+    previous_by_identity: dict[SourceFreshnessIdentity, SourceFreshnessRecord] = (
+        previous_records if previous_records is not None else {}
+    )
+    previous_by_source_name: dict[str, SourceFreshnessRecord] = (
+        previous_records_by_source_name if previous_records_by_source_name is not None else {}
+    )
+    compare_state: bool = (
+        previous_records is not None or previous_records_by_source_name is not None
+    )
+    source: SourceEntry
+    for source in selected_sources:
+        observation_source: SourceEntry | None = _source_for_observation(
+            adapter=adapter,
+            source=source,
+        )
+        if observation_source is None:
+            results.append(
+                FreshnessSourceResult(
+                    name=source.name,
+                    status=FreshnessSourceStatus.UNKNOWN,
+                    target_database=source.database,
+                    target_schema=source.schema,
+                    target_name=source.table,
+                    message="no freshness config and adapter metadata unavailable",
+                )
+            )
+            continue
+        try:
+            observation: SourceFreshnessObservation = observe_configured_source_freshness(
+                adapter=adapter,
+                connection=connection,
+                source=observation_source,
+                observed_at=observed_at,
+            )
+        except Exception as exc:
+            results.append(
+                FreshnessSourceResult(
+                    name=source.name,
+                    status=FreshnessSourceStatus.ERROR,
+                    target_database=source.database,
+                    target_schema=source.schema,
+                    target_name=source.table,
+                    message=str(exc),
+                )
+            )
+            continue
+        record: SourceFreshnessRecord = _record_from_observation(
+            observation=observation,
+            source=observation_source,
+            run_id="freshness",
+        )
+        results.append(
+            _source_result_from_record(
+                name=source.name,
+                current_record=record,
+                previous_record=previous_by_identity.get(record.identity)
+                or previous_by_source_name.get(record.source_name),
+                lag_tolerance=observation_source.freshness.lag_tolerance
+                if observation_source.freshness is not None
+                else None,
+                compare_state=compare_state,
+            )
+        )
+    return FreshnessCommandResult(sources=tuple(sorted(results, key=lambda item: item.name)))
+
+
+def _record_from_observation(
+    *, observation: SourceFreshnessObservation, source: SourceEntry, run_id: str
+) -> SourceFreshnessRecord:
+    normalized_data_version: str = normalize_source_freshness_data_version(
+        value=observation.data_version,
+        value_kind=observation.value_kind,
+    )
+    return SourceFreshnessRecord(
+        source_name=observation.source_name,
+        target_database=source.database,
+        target_schema=source.schema,
+        target_name=source.table,
+        run_id=run_id,
+        strategy=observation.strategy.value,
+        value_kind=observation.value_kind.value,
+        data_version=normalized_data_version,
+        data_version_hash=source_freshness_data_version_hash(
+            source_name=observation.source_name,
+            strategy=observation.strategy,
+            value_kind=observation.value_kind,
+            data_version=normalized_data_version,
+        ),
+        observed_at=observation.observed_at,
+    )
+
+
+def _source_result_from_record(
+    *,
+    name: str,
+    current_record: SourceFreshnessRecord,
+    previous_record: SourceFreshnessRecord | None,
+    lag_tolerance: str | None,
+    compare_state: bool,
+) -> FreshnessSourceResult:
+    if previous_record is None:
+        if compare_state:
+            return FreshnessSourceResult(
+                name=name,
+                status=FreshnessSourceStatus.UNKNOWN,
+                strategy=current_record.strategy,
+                value_kind=current_record.value_kind,
+                current_data_version=current_record.data_version,
+                lag_tolerance=lag_tolerance,
+                target_database=current_record.target_database,
+                target_schema=current_record.target_schema,
+                target_name=current_record.target_name,
+                message="previous source freshness state missing",
+            )
+        return FreshnessSourceResult(
+            name=name,
+            status=FreshnessSourceStatus.OBSERVED,
+            strategy=current_record.strategy,
+            value_kind=current_record.value_kind,
+            current_data_version=current_record.data_version,
+            lag_tolerance=lag_tolerance,
+            target_database=current_record.target_database,
+            target_schema=current_record.target_schema,
+            target_name=current_record.target_name,
+        )
+    equivalent: bool = source_freshness_records_equivalent(
+        previous_record=previous_record,
+        current_record=current_record,
+        lag_tolerance=lag_tolerance,
+    )
+    status: FreshnessSourceStatus
+    if equivalent and previous_record.data_version_hash == current_record.data_version_hash:
+        status = FreshnessSourceStatus.UNCHANGED
+    elif equivalent:
+        status = FreshnessSourceStatus.TOLERATED
+    else:
+        status = FreshnessSourceStatus.CHANGED
+    return FreshnessSourceResult(
+        name=name,
+        status=status,
+        strategy=current_record.strategy,
+        value_kind=current_record.value_kind,
+        current_data_version=current_record.data_version,
+        previous_data_version=previous_record.data_version,
+        lag_tolerance=lag_tolerance,
+        target_database=current_record.target_database,
+        target_schema=current_record.target_schema,
+        target_name=current_record.target_name,
+    )
+
+
+def _selected_sources(
+    *, sources: tuple[SourceEntry, ...], select: tuple[str, ...], exclude: tuple[str, ...]
+) -> tuple[SourceEntry, ...]:
+    selected_names: frozenset[str] = frozenset(select)
+    excluded_names: frozenset[str] = frozenset(exclude)
+    return tuple(
+        source
+        for source in sources
+        if (not selected_names or source.name in selected_names)
+        and source.name not in excluded_names
+    )
+
+
+def _source_for_observation(*, adapter: StrictAdapter, source: SourceEntry) -> SourceEntry | None:
+    if source.freshness is not None:
+        return source
+    if (
+        source.expression is None
+        and source.table is not None
+        and adapter.supports_table_freshness_metadata()
+    ):
+        return _source_with_adapter_freshness(source)
+    return None
+
+
+def _source_with_adapter_freshness(source: SourceEntry) -> SourceEntry:
+    return SourceEntry(
+        name=source.name,
+        database=source.database,
+        schema=source.schema,
+        table=source.table,
+        loader=source.loader,
+        managed=source.managed,
+        integration_loader=source.integration_loader,
+        freshness=SourceFreshnessConfig(strategy=SourceFreshnessStrategy.ADAPTER),
+        write_strategy=source.write_strategy,
+        load_batch_size=source.load_batch_size,
+        cursor_column=source.cursor_column,
+        unique_key=source.unique_key,
+        expression=source.expression,
+        description=source.description,
+        type_enforcement=source.type_enforcement,
+        contract=source.contract,
+        meta=source.meta,
+        columns=source.columns,
+        audits=source.audits,
+    )