sqlbuild 0.3.0__tar.gz → 0.4.0__tar.gz

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

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

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.4.0](https://github.com/chio-labs/sqlbuild/compare/v0.3.0...v0.4.0) (2026-05-05)
+
+
+### Features
+
+* add debug command ([b7a67f5](https://github.com/chio-labs/sqlbuild/commit/b7a67f5fbc4bcb963ac36988f6a18a9127742d91))
+* add debug command ([1193f75](https://github.com/chio-labs/sqlbuild/commit/1193f75149787bac84f3907ef166409020a64814))
+
 ## [0.3.0](https://github.com/chio-labs/sqlbuild/compare/v0.2.1...v0.3.0) (2026-05-05)
 
 

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlbuild
-Version: 0.3.0
+Version: 0.4.0
 Summary: Batch SQL transformation framework
 License-File: LICENSE
 Requires-Python: >=3.12

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlbuild"
-version = "0.3.0"
+version = "0.4.0"
 description = "Batch SQL transformation framework"
 readme = "README.md"
 requires-python = ">=3.12"

sqlbuild-0.4.0/src/sqlbuild/cli/commands/main/debug.py

@@ -0,0 +1,32 @@
+"""CLI debug command entry point."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from sqlbuild.cli.commands.main.helpers.debug.checks import build_debug_result
+from sqlbuild.cli.commands.main.helpers.debug.models import DebugResult
+from sqlbuild.cli.commands.main.helpers.debug.output import format_debug_json, format_debug_text
+from sqlbuild.shared.helpers.colors import supports_color
+
+
+def run_debug(
+    project_dir: Path | None,
+    no_color: bool = False,
+    no_connection: bool = False,
+    json_output: bool = False,
+) -> int:
+    """Validate project config and the active connection."""
+
+    effective_project_dir: Path = project_dir if project_dir is not None else Path.cwd()
+    result: DebugResult = build_debug_result(
+        project_dir=effective_project_dir,
+        check_connection=not no_connection,
+    )
+    if json_output:
+        sys.stdout.write(format_debug_json(result) + "\n")
+    else:
+        sys.stdout.write(format_debug_text(result, use_color=(not no_color) and supports_color()))
+    sys.stdout.flush()
+    return 0 if result.success else 1

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/src/sqlbuild/cli/commands/main/entry.py

@@ -90,6 +90,9 @@ def _build_parser() -> argparse.ArgumentParser:
     diff_parser.add_argument("--max-column-examples", type=int, default=None)
     diff_parser.add_argument("--max-row-only-examples", type=int, default=None)
     add_select_args(diff_parser)
+    debug_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.DEBUG)
+    debug_parser.add_argument("--json", action="store_true", default=False)
+    debug_parser.add_argument("--no-connection", action="store_true", default=False)
     query_parser: argparse.ArgumentParser = subparsers.add_parser(CliCommand.QUERY)
     query_parser.add_argument("query_sql", nargs="?", metavar="sql")
     query_parser.add_argument(
@@ -134,6 +137,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     from sqlbuild.cli.commands.main.build import run_build
     from sqlbuild.cli.commands.main.clone import run_clone
     from sqlbuild.cli.commands.main.compile import run_compile
+    from sqlbuild.cli.commands.main.debug import run_debug
     from sqlbuild.cli.commands.main.diff import run_diff
     from sqlbuild.cli.commands.main.janitor import run_janitor
     from sqlbuild.cli.commands.main.lineage import run_lineage
@@ -154,6 +158,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         run_clone=run_clone,
         run_diff=run_diff,
         run_query=run_query,
+        run_debug=run_debug,
         run_lineage=run_lineage,
         run_janitor=run_janitor,
     )
@@ -327,6 +332,13 @@ def _main_with_dependencies(
                 args.query_format,
                 query_limit,
             )
+        if args.command == CliCommand.DEBUG:
+            return handlers.run_debug(
+                project_dir,
+                args.no_color,
+                args.no_connection,
+                args.json,
+            )
         if args.command == CliCommand.JANITOR:
             return handlers.run_janitor(
                 project_dir,

sqlbuild-0.4.0/src/sqlbuild/cli/commands/main/helpers/debug/__init__.py

@@ -0,0 +1 @@
+"""Debug command helper package."""

sqlbuild-0.4.0/src/sqlbuild/cli/commands/main/helpers/debug/checks.py

@@ -0,0 +1,209 @@
+"""Debug command check execution helpers."""
+
+from __future__ import annotations
+
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from sqlbuild.adapter.base.base_adapter import BaseAdapter
+from sqlbuild.cli.commands.main.helpers.debug.models import DebugLine, DebugResult
+from sqlbuild.cli.commands.main.helpers.debug.types import DebugCheckStatus
+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.compiler.discovery.main.discover import discover_project_inputs
+from sqlbuild.compiler.discovery.models import DiscoveredProjectInputs
+from sqlbuild.spec.models.project import resolve_effective_adapter_name
+
+_SECRET_CONNECTION_KEYS: frozenset[str] = frozenset(
+    {
+        "password",
+        "private_key",
+        "private_key_file_pwd",
+        "secret",
+        "token",
+    }
+)
+
+
+def build_debug_result(*, project_dir: Path, check_connection: bool) -> DebugResult:
+    discovered_inputs: DiscoveredProjectInputs = discover_project_inputs(project_dir=project_dir)
+    local_config_path: Path = project_dir / "sqlbuild_local.yml"
+    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=project_dir)
+    connection_config: dict[str, object] = resolve_project_connection_config(
+        discovered_inputs=discovered_inputs,
+        project_dir=project_dir,
+    )
+    runtime: list[DebugLine] = _build_runtime_lines()
+    configuration: list[DebugLine] = [
+        DebugLine(
+            label="project file",
+            message=str(project_dir / "sqlbuild_project.yml"),
+            status=DebugCheckStatus.OK,
+            status_message="found and valid",
+        ),
+        DebugLine(
+            label="local config",
+            message=str(local_config_path) if local_config_path.exists() else "not present",
+            status=DebugCheckStatus.OK,
+            status_message="found" if local_config_path.exists() else "not present",
+        ),
+        DebugLine(
+            label="project",
+            message=discovered_inputs.project_config.name,
+            status=DebugCheckStatus.OK,
+            status_message="loaded",
+        ),
+        DebugLine(
+            label="adapter",
+            message=adapter_name,
+            status=DebugCheckStatus.OK,
+            status_message="found",
+        ),
+        DebugLine(
+            label="environment",
+            message=_resolve_environment_label(discovered_inputs=discovered_inputs),
+            status=DebugCheckStatus.OK,
+            status_message="resolved",
+        ),
+    ]
+    connection: list[DebugLine] = _build_connection_config_lines(connection_config)
+    _append_connection_checks(
+        connection_lines=connection,
+        adapter=adapter,
+        connection_config=connection_config,
+        check_connection=check_connection,
+    )
+    return DebugResult(
+        runtime=tuple(runtime),
+        configuration=tuple(configuration),
+        connection=tuple(connection),
+    )
+
+
+def _build_runtime_lines() -> list[DebugLine]:
+    try:
+        sqlbuild_version: str = version("sqlbuild")
+    except PackageNotFoundError:
+        sqlbuild_version = "unknown"
+    return [
+        DebugLine(label="sqlbuild version", message=sqlbuild_version),
+        DebugLine(label="python version", message=platform.python_version()),
+        DebugLine(label="python path", message=sys.executable),
+        DebugLine(label="os info", message=platform.platform()),
+    ]
+
+
+def _resolve_environment_label(*, discovered_inputs: DiscoveredProjectInputs) -> str:
+    environment: str | None = discovered_inputs.local_config.environment
+    if environment is not None:
+        return environment
+    if discovered_inputs.project_config.default_environment is not None:
+        return discovered_inputs.project_config.default_environment
+    return "default"
+
+
+def _build_connection_config_lines(connection_config: dict[str, object]) -> list[DebugLine]:
+    if not connection_config:
+        return [DebugLine(label="settings", message="no keys", status=DebugCheckStatus.OK)]
+    return [
+        DebugLine(label=key, message=_sanitize_connection_value(key=key, value=value))
+        for key, value in sorted(connection_config.items())
+    ]
+
+
+def _append_connection_checks(
+    *,
+    connection_lines: list[DebugLine],
+    adapter: BaseAdapter,
+    connection_config: dict[str, object],
+    check_connection: bool,
+) -> None:
+    if not check_connection:
+        connection_lines.append(
+            DebugLine(
+                label="connection test",
+                message="",
+                status=DebugCheckStatus.SKIP,
+                status_message="skipped by --no-connection",
+            )
+        )
+        connection_lines.append(
+            DebugLine(
+                label="query test",
+                message="",
+                status=DebugCheckStatus.SKIP,
+                status_message="connection skipped",
+            )
+        )
+        return
+
+    connection: object | None = None
+    try:
+        connection = adapter.connect(connection_config)
+        connection_lines.append(
+            DebugLine(
+                label="connection test",
+                message="",
+                status=DebugCheckStatus.OK,
+                status_message="connected",
+            )
+        )
+    except Exception as error:
+        connection_lines.append(
+            DebugLine(
+                label="connection test",
+                message="",
+                status=DebugCheckStatus.ERROR,
+                status_message=str(error),
+            )
+        )
+        connection_lines.append(
+            DebugLine(
+                label="query test",
+                message="",
+                status=DebugCheckStatus.SKIP,
+                status_message="connection failed",
+            )
+        )
+        return
+
+    try:
+        adapter.query(connection, "SELECT 1", limit=None)
+        connection_lines.append(
+            DebugLine(
+                label="query test",
+                message="",
+                status=DebugCheckStatus.OK,
+                status_message="SELECT 1",
+            )
+        )
+    except Exception as error:
+        connection_lines.append(
+            DebugLine(
+                label="query test",
+                message="",
+                status=DebugCheckStatus.ERROR,
+                status_message=str(error),
+            )
+        )
+    finally:
+        adapter.close(connection)
+
+
+def _sanitize_connection_value(*, key: str, value: object) -> str:
+    if key.lower() in _SECRET_CONNECTION_KEYS:
+        return "****"
+    if value is None:
+        return "null"
+    if isinstance(value, bool | int | float):
+        return str(value)
+    text: str = str(value)
+    if len(text) <= 32:
+        return text
+    return f"{text[:4]}...{text[-4:]}"

sqlbuild-0.4.0/src/sqlbuild/cli/commands/main/helpers/debug/models.py

@@ -0,0 +1,30 @@
+"""Debug command output models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlbuild.cli.commands.main.helpers.debug.types import DebugCheckStatus
+
+
+@dataclass(frozen=True)
+class DebugLine:
+    label: str
+    message: str
+    status: DebugCheckStatus | None = None
+    status_message: str | None = None
+
+
+@dataclass(frozen=True)
+class DebugResult:
+    runtime: tuple[DebugLine, ...]
+    configuration: tuple[DebugLine, ...]
+    connection: tuple[DebugLine, ...]
+
+    @property
+    def success(self) -> bool:
+        return all(line.status != DebugCheckStatus.ERROR for line in self.lines)
+
+    @property
+    def lines(self) -> tuple[DebugLine, ...]:
+        return self.runtime + self.configuration + self.connection

sqlbuild-0.4.0/src/sqlbuild/cli/commands/main/helpers/debug/output.py

@@ -0,0 +1,67 @@
+"""Debug command output helpers."""
+
+from __future__ import annotations
+
+import json
+
+from sqlbuild.cli.commands.main.helpers.debug.models import DebugLine, DebugResult
+from sqlbuild.cli.commands.main.helpers.debug.types import DebugCheckStatus
+from sqlbuild.shared.helpers.colors import bold, dim, green, green_bold, red
+
+
+def format_debug_text(result: DebugResult, *, use_color: bool) -> str:
+    header: str = green_bold("SQLBuild Diagnostics") if use_color else "SQLBuild Diagnostics"
+    lines: list[str] = ["", header, ""]
+    _append_section(lines, "Runtime", result.runtime, use_color=use_color)
+    _append_section(lines, "Configuration", result.configuration, use_color=use_color)
+    _append_section(lines, "Connection", result.connection, use_color=use_color)
+    return "\n".join(lines) + "\n"
+
+
+def format_debug_json(result: DebugResult) -> str:
+    return json.dumps(
+        {
+            "success": result.success,
+            "runtime": [_line_to_json(line) for line in result.runtime],
+            "configuration": [_line_to_json(line) for line in result.configuration],
+            "connection": [_line_to_json(line) for line in result.connection],
+        },
+        sort_keys=True,
+    )
+
+
+def _append_section(
+    lines: list[str], section_name: str, section_lines: tuple[DebugLine, ...], *, use_color: bool
+) -> None:
+    rendered_section_name: str = bold(f"{section_name}:") if use_color else f"{section_name}:"
+    lines.append(rendered_section_name)
+    line: DebugLine
+    for line in section_lines:
+        message: str = line.message
+        if line.status is not None:
+            status_message: str = line.status_message or line.message
+            status: str = _format_status(line.status, status_message, use_color=use_color)
+            message = status if not message else f"{message} {status}"
+        lines.append(f"  {line.label}: {message}")
+    lines.append("")
+
+
+def _format_status(status: DebugCheckStatus, message: str, *, use_color: bool) -> str:
+    status_text: str = "OK" if status == DebugCheckStatus.OK else status.value
+    rendered: str = f"[{status_text} {message}]"
+    if not use_color:
+        return rendered
+    if status == DebugCheckStatus.OK:
+        return green(rendered)
+    if status == DebugCheckStatus.ERROR:
+        return red(rendered)
+    return dim(rendered)
+
+
+def _line_to_json(line: DebugLine) -> dict[str, str]:
+    payload: dict[str, str] = {"label": line.label, "message": line.message}
+    if line.status is not None:
+        payload["status"] = line.status.value
+    if line.status_message is not None:
+        payload["status_message"] = line.status_message
+    return payload

sqlbuild-0.4.0/src/sqlbuild/cli/commands/main/helpers/debug/types.py

@@ -0,0 +1,11 @@
+"""Debug command helper types."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class DebugCheckStatus(StrEnum):
+    OK = "OK"
+    ERROR = "ERROR"
+    SKIP = "SKIP"

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/src/sqlbuild/cli/commands/main/helpers/entry/models.py

@@ -45,6 +45,7 @@ class CliNamespace:
     lineage_format: str = "tree"
     lineage_direction: str = "upstream"
     lineage_depth: str = "all"
+    no_connection: bool = False
     full: bool = False
     schema_only: bool = False
     select: list[str] = field(default_factory=list)
@@ -132,6 +133,7 @@ class CliEntrypointHandlers:
         int,
     ]
     run_query: Callable[[Path | None, str | None, str, int | None], int]
+    run_debug: Callable[[Path | None, bool, bool, bool], int]
     run_lineage: Callable[
         [Path | None, bool, str | None, str, str, str, tuple[str, ...], tuple[str, ...]],
         int,

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/src/sqlbuild/cli/commands/main/shared/types.py

@@ -15,6 +15,7 @@ class CliCommand(StrEnum):
     SEED = "seed"
     CLONE = "clone"
     DIFF = "diff"
+    DEBUG = "debug"
     LINEAGE = "lineage"
     QUERY = "query"
     CLEAN = "clean"

sqlbuild-0.4.0/tests/e2e/src/sqlbuild/cli/commands/main/debug/__init__.py

@@ -0,0 +1 @@
+"""Debug command e2e tests."""

sqlbuild-0.4.0/tests/e2e/src/sqlbuild/cli/commands/main/debug/_test_types.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DebugCliTestCase:
+    description: str
+    command: tuple[str, ...]
+    expected_stdout_fragment: str
+    expected_returncode: int = 0
+
+
+@dataclass(frozen=True)
+class DebugJsonCliTestCase:
+    description: str
+    command: tuple[str, ...]
+    expected_success: bool
+    expected_check_tail: list[dict[str, str]]

sqlbuild-0.4.0/tests/e2e/src/sqlbuild/cli/commands/main/debug/test_debug.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tests.e2e.src.sqlbuild.cli.commands.main.debug._test_types import (
+    DebugCliTestCase,
+    DebugJsonCliTestCase,
+)
+from tests.e2e.src.sqlbuild.cli.commands.main.shared.helpers import (
+    prepare_inline_project,
+    run_sqb,
+)
+
+DEBUG_CLI_TEST_CASES: list[DebugCliTestCase] = [
+    DebugCliTestCase(
+        description="checks duckdb connection by default",
+        command=("debug",),
+        expected_stdout_fragment=(
+            "  connection test: [OK connected]\n  query test: [OK SELECT 1]\n"
+        ),
+    ),
+    DebugCliTestCase(
+        description="skips connection when requested",
+        command=("debug", "--no-connection"),
+        expected_stdout_fragment=(
+            "  connection test: [SKIP skipped by --no-connection]\n"
+            "  query test: [SKIP connection skipped]\n"
+        ),
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    DEBUG_CLI_TEST_CASES,
+    ids=[case.description for case in DEBUG_CLI_TEST_CASES],
+)
+def test_given_debug_command_when_running_then_outputs_checks(
+    tmp_path: Path,
+    test_case: DebugCliTestCase,
+) -> None:
+    project_dir: Path = prepare_inline_project(
+        tmp_path=tmp_path,
+        project_name="debug_project",
+        repo_files={
+            "sqlbuild_project.yml": (
+                "name: debug_project\nadapter: duckdb\nconnection:\n  database: debug.duckdb\n"
+            ),
+        },
+    )
+
+    result: subprocess.CompletedProcess[str] = run_sqb(
+        command=test_case.command,
+        project_dir=project_dir,
+    )
+
+    assert result.returncode == test_case.expected_returncode, result.stderr
+    assert result.stdout.startswith("\nSQLBuild Diagnostics\n\n")
+    assert "Runtime:\n" in result.stdout
+    assert "Configuration:\n" in result.stdout
+    assert "Connection:\n" in result.stdout
+    assert "  database: " in result.stdout
+    assert test_case.expected_stdout_fragment in result.stdout
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [
+        DebugJsonCliTestCase(
+            description="outputs machine readable skipped connection checks",
+            command=("debug", "--json", "--no-connection"),
+            expected_success=True,
+            expected_check_tail=[
+                {
+                    "label": "connection test",
+                    "message": "",
+                    "status": "SKIP",
+                    "status_message": "skipped by --no-connection",
+                },
+                {
+                    "label": "query test",
+                    "message": "",
+                    "status": "SKIP",
+                    "status_message": "connection skipped",
+                },
+            ],
+        )
+    ],
+    ids=["outputs machine readable skipped connection checks"],
+)
+def test_given_debug_json_when_running_then_outputs_machine_readable_checks(
+    tmp_path: Path,
+    test_case: DebugJsonCliTestCase,
+) -> None:
+    project_dir: Path = prepare_inline_project(
+        tmp_path=tmp_path,
+        project_name="debug_json_project",
+        repo_files={
+            "sqlbuild_project.yml": (
+                "name: debug_json_project\nadapter: duckdb\nconnection:\n  database: debug.duckdb\n"
+            ),
+        },
+    )
+
+    result: subprocess.CompletedProcess[str] = run_sqb(
+        command=test_case.command,
+        project_dir=project_dir,
+    )
+
+    assert result.returncode == 0, result.stderr
+    payload: dict[str, object] = json.loads(result.stdout)
+    assert payload["success"] is test_case.expected_success
+    connection: list[dict[str, str]] = payload["connection"]  # type: ignore[assignment]
+    assert connection[-2:] == test_case.expected_check_tail

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/tests/unit/src/sqlbuild/cli/commands/main/entry/helpers.py

@@ -25,6 +25,7 @@ def build_handlers(**overrides: Any) -> CliEntrypointHandlers:
         run_clone=overrides.get("run_clone", noop_handler),
         run_diff=overrides.get("run_diff", noop_handler),
         run_query=overrides.get("run_query", noop_handler),
+        run_debug=overrides.get("run_debug", noop_handler),
         run_lineage=overrides.get("run_lineage", noop_handler),
         run_janitor=overrides.get("run_janitor", noop_handler),
     )

{sqlbuild-0.3.0 → sqlbuild-0.4.0}/tests/unit/src/sqlbuild/cli/commands/main/entry/test_main.py

@@ -278,6 +278,41 @@ def test_given_query_command_arguments_when_running_with_dependencies_then_it_di
     assert received_args == [(None, "select 1 as id", "table", 5)]
 
 
+@pytest.mark.parametrize(
+    "test_case",
+    [
+        MainTestCase(
+            description="dispatches debug command through injected handler",
+            argv=["--no-color", "debug", "--no-connection", "--json"],
+            expected_exit_code=12,
+            expected_no_color=True,
+        )
+    ],
+    ids=["dispatches debug command through injected handler"],
+)
+def test_given_debug_command_arguments_when_running_with_dependencies_then_it_dispatches_handler(
+    test_case: MainTestCase,
+) -> None:
+    received_args: list[tuple[Path | None, bool, bool, bool]] = []
+
+    def run_debug(
+        project_dir: Path | None,
+        no_color: bool,
+        no_connection: bool,
+        json_output: bool,
+    ) -> int:
+        received_args.append((project_dir, no_color, no_connection, json_output))
+        return test_case.expected_exit_code
+
+    exit_code: int = _main_with_dependencies(
+        argv=test_case.argv,
+        handlers=build_handlers(run_debug=run_debug),
+    )
+
+    assert exit_code == test_case.expected_exit_code
+    assert received_args == [(None, True, True, True)]
+
+
 @pytest.mark.parametrize(
     "test_case",
     [

sqlbuild-0.4.0/tests/unit/src/sqlbuild/cli/commands/main/helpers/debug/__init__.py

@@ -0,0 +1 @@
+"""Debug helper tests."""

sqlbuild-0.4.0/tests/unit/src/sqlbuild/cli/commands/main/helpers/debug/_test_types.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlbuild.cli.commands.main.helpers.debug.models import DebugResult
+
+
+@dataclass(frozen=True)
+class DebugOutputTestCase:
+    description: str
+    result: DebugResult
+    expected_text: str
+    expected_json_fragment: str