fix: keep offline modes working without a connection

`sqb test --inspect` only compiles and prints the test plan, but it resolved the connection eagerly and failed with D001 on projects without one; it now skips the connection requirement. Build validates target execution limits from the project adapter before resolving the connection, so limit errors no longer depend on a configured connection. `sqb freshness` resolves the connection only when sources are selected.

Author: kvlonge

src/sqlbuild/.agents/skills/sqlbuild/references/docs/concepts/project-configuration.md

@@ -150,8 +150,9 @@ schema = "dev"    # uses connections.local, the only named connection
 
 A command that needs the warehouse, such as `build`, `plan`, `query`, `diff`, or `debug`, fails
 with `D001` before connecting when no connection is configured at all: no named connection, no
-legacy `[connection]` block, and no inline target connection. Commands that do not connect,
-such as `compile`, `format`, `lineage`, `scope`, `rename`, and `mv`, keep working without one.
+legacy `[connection]` block, and no inline target connection. Commands and modes that do not
+connect, such as `compile`, `format`, `lineage`, `scope`, `rename`, `mv`, `test --inspect`, and
+`scenario test --local`, keep working without one.
 SQLBuild never falls back to an implicit in-memory DuckDB database; to use one, set it
 explicitly:
 

src/sqlbuild/cli/commands/_helpers/build_planning/invocation.py

@@ -6,12 +6,11 @@
 from pathlib import Path
 from typing import TextIO
 
-from sqlbuild.cli.commands._helpers.runtime.adapter_context import (
-    resolve_adapter_connection_context,
-)
+from sqlbuild.adapter.contract.classes.base_adapter import BaseAdapter
+from sqlbuild.cli.commands._helpers.runtime.adapters import resolve_adapter
+from sqlbuild.cli.commands._helpers.runtime.connection import resolve_project_connection_config
 from sqlbuild.cli.commands.exceptions import CliUserError
 from sqlbuild.cli.commands.models import (
-    AdapterConnectionContext,
     BuildCommandRequest,
     BuildInvocation,
 )
@@ -23,6 +22,9 @@
 from sqlbuild.compiler.discovery.main.discover import discover_project_inputs
 from sqlbuild.compiler.discovery.models import DiscoveredProjectInputs
 from sqlbuild.presentation.main.supports_color import supports_color
+from sqlbuild.spec.contracts.main.resolve_effective_adapter_name import (
+    resolve_effective_adapter_name,
+)
 from sqlbuild.spec.contracts.main.resolve_target_config import resolve_target_config
 from sqlbuild.spec.contracts.main.resolve_target_name import resolve_target_name
 from sqlbuild.spec.contracts.models import ExecutionLimitsConfig, TargetConfig
@@ -44,17 +46,35 @@ def resolve_build_invocation(*, request: BuildCommandRequest) -> BuildInvocation
     )
     if request.defer_to is not None and effective_defer_clone_from is not None:
         raise CliUserError("--defer-clone-from cannot be used with --defer-to", code="C408")
-    adapter_context: AdapterConnectionContext = resolve_adapter_connection_context(
+    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=adapter_name, project_dir=effective_project_dir
+    )
+    effective_target_name: str | None = resolve_target_name(
+        project_config=discovered_inputs.project_config,
+        local_config=discovered_inputs.local_config,
+        selected_target=request.selected_target,
+    )
+    execution_limits: ExecutionLimitsConfig = _resolve_execution_limits(
         discovered_inputs=discovered_inputs,
-        effective_project_dir=effective_project_dir,
+        target_name=effective_target_name,
+        adapter_name=adapter_name,
+        adapter=adapter,
+    )
+    connection_config: dict[str, object] = resolve_project_connection_config(
+        discovered_inputs=discovered_inputs,
+        project_dir=effective_project_dir,
         selected_target=request.selected_target,
         cli_vars=request.cli_vars,
     )
     machine_output: bool = request.json_output
     use_color: bool = not request.no_color and not machine_output and supports_color()
     progress_stream: TextIO = sys.stderr if request.debug or machine_output else sys.stdout
     reporters: CommandProgressReporters = build_command_progress_reporters(
-        adapter_name=adapter_context.adapter_name,
+        adapter_name=adapter_name,
         stream=progress_stream,
         use_color=use_color,
     )
@@ -63,59 +83,65 @@ def resolve_build_invocation(*, request: BuildCommandRequest) -> BuildInvocation
         if request.load_sources is not None
         else build_effective_settings_config(discovered_inputs=discovered_inputs).auto_load_sources
     )
-    effective_target_name: str | None = resolve_target_name(
-        project_config=discovered_inputs.project_config,
-        local_config=discovered_inputs.local_config,
-        selected_target=request.selected_target,
+    return BuildInvocation(
+        effective_project_dir=effective_project_dir,
+        discovered_inputs=discovered_inputs,
+        effective_defer_clone_from=effective_defer_clone_from,
+        adapter_name=adapter_name,
+        adapter=adapter,
+        connection_config=connection_config,
+        use_color=use_color,
+        progress_stream=progress_stream,
+        connection_progress=reporters.connection,
+        planning_progress=reporters.planning,
+        should_load_sources=should_load_sources,
+        effective_target_name=effective_target_name,
+        execution_limits=execution_limits,
     )
+
+
+def _resolve_execution_limits(
+    *,
+    discovered_inputs: DiscoveredProjectInputs,
+    target_name: str | None,
+    adapter_name: str,
+    adapter: BaseAdapter,
+) -> ExecutionLimitsConfig:
+    """Resolve the target's execution limits and validate them against the project adapter."""
+
     execution_limits: ExecutionLimitsConfig = (
         resolve_target_config(
             project_config=discovered_inputs.project_config,
             local_config=discovered_inputs.local_config,
-            target_name=effective_target_name,
+            target_name=target_name,
         ).execution_limits
-        if effective_target_name is not None
+        if target_name is not None
         else ExecutionLimitsConfig()
     )
+    target_label: str = target_name or "default"
     if (
         execution_limits.max_duration is not None
-        and adapter_context.adapter.execution_duration_limit_seconds is None
+        and adapter.execution_duration_limit_seconds is None
     ):
-        target_label: str = effective_target_name or "default"
         raise CliUserError(
             f"Target '{target_label}' configures max_duration, but adapter "
-            f"'{adapter_context.adapter_name}' cannot cancel active statements safely",
+            f"'{adapter_name}' cannot cancel active statements safely",
             code="C415",
             help=execution_limits.remediation,
         )
-    maximum_duration_seconds: int | None = adapter_context.adapter.execution_duration_limit_seconds
+    maximum_duration_seconds: int | None = adapter.execution_duration_limit_seconds
     if (
         execution_limits.max_duration_seconds is not None
         and maximum_duration_seconds is not None
         and execution_limits.max_duration_seconds > maximum_duration_seconds
     ):
-        target_label = effective_target_name or "default"
         raise CliUserError(
             f"Target '{target_label}' max_duration exceeds the largest duration supported by "
-            f"adapter '{adapter_context.adapter_name}' ({maximum_duration_seconds} seconds)",
+            f"adapter '{adapter_name}' ({maximum_duration_seconds} seconds)",
             code="C416",
             help=execution_limits.remediation,
         )
-    return BuildInvocation(
-        effective_project_dir=effective_project_dir,
-        discovered_inputs=discovered_inputs,
-        effective_defer_clone_from=effective_defer_clone_from,
-        adapter_name=adapter_context.adapter_name,
-        adapter=adapter_context.adapter,
-        connection_config=adapter_context.connection_config,
-        use_color=use_color,
-        progress_stream=progress_stream,
-        connection_progress=reporters.connection,
-        planning_progress=reporters.planning,
-        should_load_sources=should_load_sources,
-        effective_target_name=effective_target_name,
-        execution_limits=execution_limits,
-    )
+    return execution_limits
 
 
 def _resolve_defer_clone_from(

src/sqlbuild/cli/commands/_helpers/runtime/adapter_context.py

@@ -20,6 +20,7 @@ def resolve_adapter_connection_context(
     effective_project_dir: Path,
     selected_target: str | None,
     cli_vars: dict[str, object] | None,
+    require_connection: bool = True,
 ) -> AdapterConnectionContext:
     """Resolve the effective adapter and project connection configuration."""
 
@@ -36,6 +37,7 @@ def resolve_adapter_connection_context(
         project_dir=effective_project_dir,
         selected_target=selected_target,
         cli_vars=cli_vars,
+        require_connection=require_connection,
     )
     return AdapterConnectionContext(
         adapter_name=adapter_name,

src/sqlbuild/cli/commands/_helpers/runtime/command_invocation.py

@@ -54,7 +54,9 @@ def resolve_command_invocation[InvocationT](
 ) -> InvocationT:
     """Resolve discovery, adapter, connection, and output context for one command."""
 
-    context: _CommandInvocationContext = _resolve_command_invocation_context(request=request)
+    context: _CommandInvocationContext = _resolve_command_invocation_context(
+        request=request, require_connection=True
+    )
     return invocation_type(
         effective_project_dir=context.effective_project_dir,
         discovered_inputs=context.discovered_inputs,
@@ -67,11 +69,16 @@ def resolve_command_invocation[InvocationT](
 
 
 def resolve_reported_command_invocation[InvocationT](
-    *, request: _CommandInvocationRequest, invocation_type: Callable[..., InvocationT]
+    *,
+    request: _CommandInvocationRequest,
+    invocation_type: Callable[..., InvocationT],
+    require_connection: bool = True,
 ) -> InvocationT:
     """Resolve command context plus shared connection and planning progress reporters."""
 
-    context: _CommandInvocationContext = _resolve_command_invocation_context(request=request)
+    context: _CommandInvocationContext = _resolve_command_invocation_context(
+        request=request, require_connection=require_connection
+    )
     reporters: CommandProgressReporters = build_command_progress_reporters(
         adapter_name=context.adapter_context.adapter_name,
         stream=context.progress_stream,
@@ -91,7 +98,7 @@ def resolve_reported_command_invocation[InvocationT](
 
 
 def _resolve_command_invocation_context(
-    *, request: _CommandInvocationRequest
+    *, request: _CommandInvocationRequest, require_connection: bool
 ) -> _CommandInvocationContext:
     effective_project_dir: Path = (
         request.project_dir if request.project_dir is not None else Path.cwd()
@@ -104,6 +111,7 @@ def _resolve_command_invocation_context(
         effective_project_dir=effective_project_dir,
         selected_target=request.selected_target,
         cli_vars=request.cli_vars,
+        require_connection=require_connection,
     )
     machine_output: bool = request.json_output
     use_color: bool = not request.no_color and not machine_output and supports_color()

src/sqlbuild/cli/commands/_helpers/runtime/connection.py

@@ -111,14 +111,16 @@ def resolve_project_connection_config(
     project_dir: Path,
     selected_target: str | None = None,
     cli_vars: dict[str, object] | None = None,
+    require_connection: bool = True,
 ) -> dict[str, object]:
-    """Resolve the effective project connection config for CLI command execution."""
+    """Resolve the project connection; offline modes pass ``require_connection=False``."""
 
-    _require_configured_connection(
-        discovered_inputs=discovered_inputs,
-        project_dir=project_dir,
-        selected_target=selected_target,
-    )
+    if require_connection:
+        _require_configured_connection(
+            discovered_inputs=discovered_inputs,
+            project_dir=project_dir,
+            selected_target=selected_target,
+        )
     return resolve_connection_config(
         raw_config=build_effective_connection_config(
             discovered_inputs=discovered_inputs,

src/sqlbuild/cli/commands/_helpers/test/invocation.py

@@ -9,6 +9,10 @@
 
 
 def resolve_test_invocation(*, request: TestCommandRequest) -> TestInvocation:
-    """Resolve discovery, adapter, connection, and reporters for test."""
+    """Resolve test context; ``--inspect`` never connects, so it needs no connection."""
 
-    return resolve_reported_command_invocation(request=request, invocation_type=TestInvocation)
+    return resolve_reported_command_invocation(
+        request=request,
+        invocation_type=TestInvocation,
+        require_connection=not request.inspect,
+    )

src/sqlbuild/cli/commands/main/execution/_freshness.py

@@ -67,12 +67,6 @@ def run_freshness(request: FreshnessCommandRequest) -> int:
     adapter: BaseAdapter = resolve_adapter(
         adapter_name=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,
-        selected_target=selected_target,
-        cli_vars=cli_vars,
-    )
     graph: ProjectGraph = build_project_graph(
         discovered_inputs=discovered_inputs,
         adapter=adapter,
@@ -91,6 +85,12 @@ def run_freshness(request: FreshnessCommandRequest) -> int:
     if not selected_source_names:
         result: FreshnessCommandResult = FreshnessCommandResult()
     else:
+        connection_config: dict[str, object] = resolve_project_connection_config(
+            discovered_inputs=discovered_inputs,
+            project_dir=effective_project_dir,
+            selected_target=selected_target,
+            cli_vars=cli_vars,
+        )
         connection: Any = adapter.connect(connection_config)
         try:
             previous_records_by_source_name: dict[str, SourceFreshnessRecord] | None = None

tests/integration/src/sqlbuild/cli/commands/main/helpers.py

@@ -791,3 +791,21 @@ def write_default_connection_project(*, project_dir: Path, project_toml: str) ->
         'MODEL (description "Orders.", materialized table);\n\nSELECT 1 AS order_id\n',
         encoding="utf-8",
     )
+
+
+def write_default_connection_sql_test(*, project_dir: Path) -> None:
+    """Add a downstream model and a SQL test that mocks its orders dependency."""
+
+    _ = (project_dir / "models" / "order_totals.sql").write_text(
+        'MODEL (description "Order totals.", materialized table);\n\n'
+        'SELECT order_id FROM __ref("orders")\n',
+        encoding="utf-8",
+    )
+    (project_dir / "tests" / "unit").mkdir(parents=True)
+    _ = (project_dir / "tests" / "unit" / "test_order_totals.sql").write_text(
+        'TEST (name "order_totals_value");\n\n'
+        "WITH __ref__orders AS (SELECT 1 AS order_id),\n"
+        "__expected__order_totals AS (SELECT 1 AS order_id)\n"
+        "SELECT 1\n",
+        encoding="utf-8",
+    )

tests/integration/src/sqlbuild/cli/commands/main/test_default_connection.py

@@ -16,6 +16,7 @@
     execute_duckdb_sql,
     query_duckdb_rows,
     write_default_connection_project,
+    write_default_connection_sql_test,
 )
 
 _ONE_CONNECTION_PROJECT: str = (
@@ -123,6 +124,13 @@ def test_given_target_without_connection_when_building_then_only_named_connectio
             expected_exit_code=0,
             expected_output_fragments=("Project compiled",),
         ),
+        DefaultConnectionCliTestCase(
+            description="freshness without selected sources works without any connection",
+            project_toml=_NO_CONNECTION_PROJECT,
+            argv=("freshness",),
+            expected_exit_code=0,
+            expected_output_fragments=("OBSERVED=0",),
+        ),
         DefaultConnectionCliTestCase(
             description="build uses an explicit in-memory connection",
             project_toml=_MEMORY_CONNECTION_PROJECT,
@@ -148,6 +156,46 @@ def test_given_target_without_connection_when_resolving_offline_then_connection_
     assert not (tmp_path / "shop.duckdb").exists()
 
 
+@pytest.mark.parametrize(
+    "test_case",
+    [
+        DefaultConnectionCliTestCase(
+            description="test inspection works without any connection",
+            project_toml=_NO_CONNECTION_PROJECT,
+            argv=("test", "--inspect"),
+            expected_exit_code=0,
+            expected_output_fragments=(
+                "boundary: orders is replaced by __ref__orders",
+                "Test plan inspection complete: 1 selected, 0 errors.",
+            ),
+        ),
+        DefaultConnectionCliTestCase(
+            description="test execution fails before connecting without any connection",
+            project_toml=_NO_CONNECTION_PROJECT,
+            argv=("test",),
+            expected_exit_code=1,
+            expected_output_fragments=("error[D001]", "target dev has no connection"),
+        ),
+    ],
+    ids=lambda case: case.description,
+)
+def test_given_no_connection_when_running_sql_tests_then_only_inspection_succeeds(
+    test_case: DefaultConnectionCliTestCase,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    write_default_connection_project(project_dir=tmp_path, project_toml=test_case.project_toml)
+    write_default_connection_sql_test(project_dir=tmp_path)
+
+    exit_code: int = main(["--no-color", "--project-dir", str(tmp_path), *test_case.argv])
+
+    output: str = "".join(capsys.readouterr())
+    assert exit_code == test_case.expected_exit_code, output
+    assert all(fragment in output for fragment in test_case.expected_output_fragments), output
+    assert "Connecting to" not in output
+    assert not (tmp_path / "shop.duckdb").exists()
+
+
 @pytest.mark.parametrize(
     "test_case",
     [

tests/unit/src/sqlbuild/cli/commands/_helpers/runtime/_test_types.py

@@ -118,3 +118,11 @@ class ExplicitMemoryConnectionTestCase:
     project_config: ProjectConfig
     local_config: LocalConfig
     expected_connection: dict[str, object]
+
+
+@dataclass(frozen=True)
+class OfflineConnectionResolutionTestCase:
+    description: str
+    project_config: ProjectConfig
+    local_config: LocalConfig
+    expected_connection: dict[str, object]