dbctl 0.7.4__tar.gz → 0.7.7__tar.gz

{dbctl-0.7.4 → dbctl-0.7.7}/CHANGELOG.md

@@ -5,6 +5,86 @@ All notable changes to this project will be documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.7] — 2026-08-10
+
+### Fixed
+
+- **`ruff format` failed in CI** on the v0.7.6 commit — three files
+  (`dbctl/cli.py`, `dbctl/runtime.py`, `tests/test_execute.py`) had
+  manually-typed signatures that fit on one line per `ruff format`'s
+  rules but were wrapped in the source. Reformatted to the canonical
+  layout (`def opened_engine(ctx: click.Context, canonical: str, conn:
+  Connection) -> Iterator[OpenedStub]:` on one line; same for the
+  `execute_cmd` callback signature and the inline-URL error `print`
+  call). Re-running `uv run ruff format --check dbctl tests` is now
+  clean and `make format` is a no-op on top of this commit.
+- **Typo in `docs/execute.md`** — `# dduckdb inline URL` comment →
+  `# duckdb inline URL`.
+- **README project layout** now lists `execute.md` under `docs/` so the
+  new reference page is discoverable from the layout block.
+
+No behaviour change; re-running `dbctl execute --help` produces the
+same output as v0.7.6.
+
+## [0.7.6] — 2026-08-10
+
+### Added
+
+- **`dbctl execute`** — run ad-hoc SQL without declaring an operation in
+  `operations.yaml`. The new top-level verb takes a connection name *or* a
+  full SQLAlchemy URL, the SQL string as a single positional argument, and
+  the short option set the existing operation dispatch uses:
+
+  ```bash
+  dbctl execute -c pg -o json "SELECT * FROM users"
+  dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+  dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+  dbctl execute -c pg -o yaml "SELECT * FROM users LIMIT 10"
+  ```
+
+  Behaviour:
+
+  - **`-c` / `--connection`** accepts a registered connection name /
+    alias (resolved via `connections.yaml`) **or** a full SQLAlchemy URL
+    (detected by the presence of `://`). Inline URLs build a transient
+    `direct` Connection so the SSM/SSH password-source plumbing, native-lib
+    install hints, and `connect_args` (connect-timeout, Windows SSO) all
+    apply uniformly.
+  - **`-o` / `--output`** chooses `table` (default) / `json` / `csv` /
+    `yaml` for SELECT-shaped results, exactly like declared `fetch` ops.
+  - The SQL is auto-classified by its first verb: `SELECT` / `WITH` /
+    `SHOW` / `EXPLAIN` / `DESCRIBE` / `PRAGMA` / `VALUES` / `TABLE` runs
+    as a query (rendered via `--output`); anything else runs as DML
+    (INSERT / UPDATE / DELETE / CREATE / DROP / ALTER / ...) inside
+    `engine.begin()`.
+  - DML respects the connection's `safety.confirm` (dry-run-by-default
+    unless `--apply`), `safety.read_only` (DML blocked with exit 6), and
+    prompts before commit unless `--yes` / `-y` is passed — exactly the
+    same gate as a declared `mode: execute` operation. Inline URLs
+    default to `safety.confirm: true`.
+  - DDL that returns `rowcount = -1` (CREATE TABLE, DROP, ...) is rendered
+    as `OK in <ms>ms` instead of the misleading `OK -1 row(s) affected`.
+    Real INSERT/UPDATE/DELETE row counts are still reported.
+  - Every run is appended to `~/.dbctl/history.jsonl` as
+    `operation="execute"` with the SQL (truncated to 500 chars) in the
+    `params.sql` field, so it shows up under `dbctl history list`. The
+    audit `connection` field is the canonical connection name, or the
+    literal `<inline>` token for inline URL runs.
+  - `--show-sql` prints the resolved SQL before executing; `--` separates
+    options from positional SQL that begins with a dash (Click would
+    otherwise treat the leading dash as an unknown option).
+  - The new verb is registered as a top-level static command alongside
+    `connections` / `operations` / `doctor` / `init` / `history` /
+    `tunnel` / `ui`, so shell completion picks it up.
+
+  This closes the long-standing "no ad-hoc query command" gap without
+  weakening the declarative operation registry: the declared
+  `operations.yaml` model remains the recommended way to make "what can
+  be run against this DB" discoverable from a versioned file, while
+  `execute` covers the exploratory / break-glass path the TUI already
+  serves — both share the same tunnel / safety / audit plumbing so every
+  run is still logged and policy-checked.
+
 ## [0.7.4] — 2026-08-10
 
 ### Added

{dbctl-0.7.4 → dbctl-0.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbctl
-Version: 0.7.4
+Version: 0.7.7
 Summary: Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection.
 Author: dbctl contributors
 License: MIT
@@ -122,9 +122,9 @@ the same params.
 
 ## Why "the operations are declarative"
 
-There is **no ad-hoc query command**. To run SQL through `dbctl` you must
-declare an operation in `operations.yaml` first — its name, its parameters
-(with types, descriptions, positional vs keyword), its SQL, and its mode
+The recommended path for permanent, repeatable work is to declare an
+operation in `operations.yaml` first — its name, its parameters (with
+types, descriptions, positional vs keyword), its SQL, and its mode
 (`execute` / `fetch` / `fetch_one` / `script` / `upsert` for single-DB;
 `diff` / `compare` / `copy` / `sync` / `validate` / `replay` for multi-DB).
 The CLI then synthesises a Click subcommand per operation, so:
@@ -135,7 +135,18 @@ The CLI then synthesises a Click subcommand per operation, so:
 - the audit log is queryable by operation name (`dbctl history list`).
 
 This keeps "what can be run against this DB" discoverable from a versioned
-config file, instead of buried in shell history.
+config file, instead of buried in shell history. For exploratory / break-glass
+SQL — the path the TUI serves — `dbctl execute` (added in v0.7.6) runs
+ad-hoc SQL through the same tunnel / safety / audit plumbing without
+requiring a declared operation:
+
+```bash
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+```
+
+See [`docs/execute.md`](docs/execute.md) for the full reference.
 
 ## Install (uv)
 
@@ -188,6 +199,12 @@ dbctl pg add-user stephen 12 --show-sql        # dry-run (prints SQL)
 dbctl pg add-user stephen 12 --apply --yes     # commit (no prompt)
 dbctl pg increase-credits alice 10 --apply -y    # +10% on alice's credits
 
+# ad-hoc SQL without declaring an operation (since v0.7.6):
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+dbctl execute -c pg -o yaml -- "SELECT * FROM users WHERE name='-alice'"  # SQL starting with a dash needs `--`
+
 # multi-DB modes (operation-first, preferred since v0.6):
 dbctl user-count pg my                        # multi-DB diff
 dbctl compare-credits pg my Daily
@@ -414,6 +431,7 @@ dbctl/
 ├── docs/
 │   ├── connections.md      # connections.yaml reference
 │   ├── operations.md       # operations.yaml reference
+│   ├── execute.md          # dbctl execute (ad-hoc SQL) reference
 │   ├── tui.md              # dbctl ui reference (keybindings, dialect SQL)
 │   └── DESIGN.md           # architecture and design decisions
 └── dbctl/

{dbctl-0.7.4 → dbctl-0.7.7}/README.md

@@ -86,9 +86,9 @@ the same params.
 
 ## Why "the operations are declarative"
 
-There is **no ad-hoc query command**. To run SQL through `dbctl` you must
-declare an operation in `operations.yaml` first — its name, its parameters
-(with types, descriptions, positional vs keyword), its SQL, and its mode
+The recommended path for permanent, repeatable work is to declare an
+operation in `operations.yaml` first — its name, its parameters (with
+types, descriptions, positional vs keyword), its SQL, and its mode
 (`execute` / `fetch` / `fetch_one` / `script` / `upsert` for single-DB;
 `diff` / `compare` / `copy` / `sync` / `validate` / `replay` for multi-DB).
 The CLI then synthesises a Click subcommand per operation, so:
@@ -99,7 +99,18 @@ The CLI then synthesises a Click subcommand per operation, so:
 - the audit log is queryable by operation name (`dbctl history list`).
 
 This keeps "what can be run against this DB" discoverable from a versioned
-config file, instead of buried in shell history.
+config file, instead of buried in shell history. For exploratory / break-glass
+SQL — the path the TUI serves — `dbctl execute` (added in v0.7.6) runs
+ad-hoc SQL through the same tunnel / safety / audit plumbing without
+requiring a declared operation:
+
+```bash
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+```
+
+See [`docs/execute.md`](docs/execute.md) for the full reference.
 
 ## Install (uv)
 
@@ -152,6 +163,12 @@ dbctl pg add-user stephen 12 --show-sql        # dry-run (prints SQL)
 dbctl pg add-user stephen 12 --apply --yes     # commit (no prompt)
 dbctl pg increase-credits alice 10 --apply -y    # +10% on alice's credits
 
+# ad-hoc SQL without declaring an operation (since v0.7.6):
+dbctl execute -c pg -o json "SELECT * FROM users"
+dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+dbctl execute -c pg -o yaml -- "SELECT * FROM users WHERE name='-alice'"  # SQL starting with a dash needs `--`
+
 # multi-DB modes (operation-first, preferred since v0.6):
 dbctl user-count pg my                        # multi-DB diff
 dbctl compare-credits pg my Daily
@@ -378,6 +395,7 @@ dbctl/
 ├── docs/
 │   ├── connections.md      # connections.yaml reference
 │   ├── operations.md       # operations.yaml reference
+│   ├── execute.md          # dbctl execute (ad-hoc SQL) reference
 │   ├── tui.md              # dbctl ui reference (keybindings, dialect SQL)
 │   └── DESIGN.md           # architecture and design decisions
 └── dbctl/

{dbctl-0.7.4 → dbctl-0.7.7}/dbctl/cli.py

@@ -20,10 +20,12 @@ from typing import Any
 import click
 import yaml
 from rich.table import Table
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
 from sqlalchemy.exc import SQLAlchemyError
 
 from dbctl import __version__
-from dbctl.config import Operation, OutputFormat, Param, ParamType
+from dbctl.config import Connection, Operation, OutputFormat, Param, ParamType
 from dbctl.operations import by_scope
 from dbctl.operations import resolve as resolve_op
 from dbctl.runtime import (
@@ -1020,7 +1022,17 @@ def _aliases(conns):
 
 def _root_list(ctx: click.Context) -> list[str]:
     conns, ops = registries(ctx)
-    static = ["connections", "operations", "status", "doctor", "init", "history", "tunnel", "ui"]
+    static = [
+        "connections",
+        "operations",
+        "status",
+        "doctor",
+        "init",
+        "history",
+        "tunnel",
+        "ui",
+        "execute",
+    ]
     # multi-op operation-first top-level commands + deprecated verb-first groups
     multi_ops = {n for n, o in ops.items() if o.scope.value == "multi"}
     multi_modes = {o.mode.value for o in ops.values() if o.scope.value == "multi"}
@@ -1040,6 +1052,7 @@ def _root_get(ctx: click.Context, name: str):
         "history": history_cmd,
         "tunnel": tunnel_cmd,
         "ui": ui_cmd,
+        "execute": execute_cmd,
     }
     if name in static:
         return static[name]
@@ -1339,6 +1352,278 @@ def ui_cmd(ctx):
     DbctlApp(profile=ctx.obj.get("profile")).run()
 
 
+# --------------------------------------------------------------------------- #
+# ad-hoc SQL: `dbctl execute`
+# --------------------------------------------------------------------------- #
+# A read-only SQL verb is one whose first word matches this set. "VALUES"
+# / "TABLE" are SQL-standard row-set constructors; "WITH" is a CTE head;
+# the rest are dialect-specific introspection verbs (EXPLAIN / DESCRIBE /
+# SHOW / PRAGMA / DESC) that return a result set the user wants to render
+# like a SELECT.
+_READ_VERBS = {
+    "SELECT",
+    "WITH",
+    "VALUES",
+    "TABLE",
+    "SHOW",
+    "EXPLAIN",
+    "DESC",
+    "DESCRIBE",
+    "PRAGMA",
+}
+
+
+def _sql_is_read(sql: str) -> bool:
+    head = sql.strip().lstrip("(").strip().split(None, 1)
+    return bool(head) and head[0].upper() in _READ_VERBS
+
+
+def _make_inline_connection(url: str) -> Connection:
+    """Build a transient ``Connection`` from a full SQLAlchemy URL.
+
+    Used by ``dbctl execute -c "<sqlalchemy url>"``. The placeholder
+    ``direct`` block is required by the ``Connection`` validator even in
+    URL mode, but it's never *used* — ``build_engine`` honours ``url:``
+    over host/port. Default safety mirrors the bundled dev connections:
+    DML is dry-run-by-default unless ``--apply`` is supplied.
+    """
+    from dbctl.config import Connection
+
+    return Connection.model_validate(
+        {
+            "type": "direct",
+            "direct": {"host": "localhost", "port": 1},
+            "url": url,
+            "healthcheck": {"query": "SELECT 1", "timeout_seconds": 5},
+            "safety": {"confirm": True, "read_only": False},
+        }
+    )
+
+
+def _do_execute_ad_hoc(
+    *,
+    engine: Engine,
+    sql: str,
+    is_select: bool,
+    output_fmt: str,
+    canonical: str,
+    profile: str | None,
+    actor: str | None,
+) -> None:
+    """Run an ad-hoc SQL string against ``engine`` and render the result.
+
+    SELECT-shaped SQL runs in a read-only ``engine.connect()`` and renders
+    via ``render_rows`` (table / json / yaml / csv). DML runs inside
+    ``engine.begin()`` and reports rows-affected with a green OK line. Any
+    SQLAlchemy / runtime error is rendered via ``fmt_db_error`` (one-line
+    friendly message) and exits 1 — matching the declared-op execution
+    path's behaviour. Every run is appended to the audit log as
+    ``operation="execute"`` with the SQL (truncated to 500 chars) in
+    ``params`` so it shows up under ``dbctl history list``.
+    """
+    from dbctl.audit import append
+    from dbctl.reports import render_rows
+
+    started = time.monotonic()
+    mode_label = "fetch" if is_select else "execute"
+    audit_sql = sql[:500]
+    rows_affected: int | None = None
+    try:
+        if is_select:
+            with engine.connect() as c:
+                rows = [dict(r) for r in c.execute(text(sql)).mappings()]
+            render_rows(rows, output_fmt, title=canonical)
+        else:
+            with engine.begin() as c:
+                result = c.execute(text(sql))
+                rows_affected = result.rowcount
+            elapsed = (time.monotonic() - started) * 1000.0
+            # Many drivers report rowcount = -1 (unknown) for DDL and for
+            # statements that don't naturally expose a row count (CREATE
+            # TABLE, DROP TABLE, ALTER, ...). Render a cleaner line instead
+            # of the misleading "OK -1 row(s) affected".
+            if rows_affected is not None and rows_affected >= 0:
+                console.print(f"[green]OK[/green] {rows_affected} row(s) affected in {elapsed:.1f}ms")
+            else:
+                console.print(f"[green]OK[/green] in {elapsed:.1f}ms")
+    except (RuntimeError, SQLAlchemyError) as e:
+        append(
+            profile=profile,
+            connection=canonical,
+            operation="execute",
+            params={"sql": audit_sql},
+            mode=mode_label,
+            status="error",
+            duration_ms=(time.monotonic() - started) * 1000.0,
+            actor=actor,
+        )
+        err_console.print(f"[red]{_fmt_db_error(e)}[/red]")
+        raise SystemExit(1)
+    append(
+        profile=profile,
+        connection=canonical,
+        operation="execute",
+        params={"sql": audit_sql},
+        mode=mode_label,
+        status="ok",
+        rows_affected=rows_affected,
+        duration_ms=(time.monotonic() - started) * 1000.0,
+        actor=actor,
+    )
+
+
+@click.command("execute", context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "-c",
+    "--connection",
+    "connection_str",
+    required=True,
+    metavar="CONN-OR-URL",
+    help=(
+        "Either a connection name / alias from connections.yaml, or a full "
+        "SQLAlchemy URL (e.g. "
+        "'postgresql+psycopg://user:pass@host:5432/db'). "
+        "URLs are detected by the presence of '://'."
+    ),
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_fmt",
+    type=click.Choice([m.value for m in OutputFormat]),
+    default="table",
+    show_default=True,
+    help="Output format for SELECT-shaped results (ignored for DML).",
+)
+@click.option(
+    "--apply",
+    is_flag=True,
+    help="Commit any DML (default is a dry-run preview when confirm is on).",
+)
+@click.option(
+    "-y",
+    "--yes",
+    is_flag=True,
+    help="Skip the confirmation prompt before DML is committed.",
+)
+@click.option(
+    "--show-sql",
+    is_flag=True,
+    help="Print the SQL before executing.",
+)
+@click.argument("sql")
+@click.pass_context
+def execute_cmd(
+    ctx: click.Context, connection_str: str, output_fmt: str, apply: bool, yes: bool, show_sql: bool, sql: str
+) -> None:
+    """Run ad-hoc SQL against a configured connection OR a full SQLAlchemy URL.
+
+    The SQL is auto-classified by its first verb: SELECT / WITH / SHOW /
+    EXPLAIN / DESCRIBE / PRAGMA / VALUES / TABLE runs as a query and is
+    rendered via ``--output`` (table / json / yaml / csv). Anything else
+    (INSERT / UPDATE / DELETE / CREATE / DROP / ALTER / ...) runs as DML
+    with the same dry-run-by-default + ``--apply`` safety semantics as a
+    declared ``mode: execute`` operation: on a connection with
+    ``safety.confirm: true`` (the default config), the SQL is previewed
+    and the audit log records a ``dry-run`` status unless ``--apply`` is
+    passed; ``--yes`` skips the final [y/N] prompt.
+
+    \b
+    Examples:
+      dbctl execute -c pg -o json "SELECT * FROM users"
+      dbctl execute -c pg --show-sql --apply "DELETE FROM users WHERE name='bob'"
+      dbctl execute -c "postgresql+psycopg://u:p@host:5432/db" -o csv "SELECT 1"
+      dbctl execute -c sqlite -o yaml "SELECT name FROM sqlite_master WHERE type='table'"
+
+    \b
+    If the SQL itself begins with a dash, separate options from the
+    positional with ``--`` (Click would otherwise treat the leading dash
+    as an unknown option):
+      dbctl execute -c pg -- "-- my SQL comment starting with a dash"
+
+    Every run is appended to ~/.dbctl/history.jsonl as
+    ``operation="execute"`` so it shows up under ``dbctl history list``;
+    the SQL (truncated to 500 chars) is recorded in the audit entry's
+    ``params.sql`` field.
+    """
+    from dbctl.connections import resolve as resolve_conn_name
+
+    sql_clean = sql.strip()
+    if not sql_clean:
+        err_console.print("[red]empty SQL statement[/red]")
+        raise SystemExit(2)
+    is_select = _sql_is_read(sql_clean)
+
+    is_url = "://" in connection_str
+    if is_url:
+        canonical = "<inline>"
+        try:
+            conn = _make_inline_connection(connection_str)
+        except Exception as e:  # noqa: BLE001 - validator / make-url errors
+            err_console.print(f"[red]invalid connection URL: {e}[/red]")
+            raise SystemExit(2)
+    else:
+        conns, _ = registries(ctx)
+        try:
+            canonical, conn = resolve_conn_name(connection_str, conns)
+        except KeyError as e:
+            err_console.print(f"[red]{e}[/red]")
+            raise SystemExit(2)
+
+    if show_sql:
+        console.print(f"[cyan]SQL:[/cyan]\n{sql_clean}")
+
+    profile = ctx.obj.get("profile")
+    actor = ctx.obj.get("actor")
+
+    # DML safety gate — mirrors `_execute_single`'s read_only / confirm / dry-run logic.
+    if not is_select:
+        if conn.safety.read_only:
+            err_console.print(f"[red]connection {canonical!r} is read-only; DML is blocked[/red]")
+            raise SystemExit(6)
+        if conn.safety.confirm and not apply:
+            console.print("[yellow]dry-run (use --apply to commit)[/yellow]")
+            from dbctl.audit import append
+
+            append(
+                profile=profile,
+                connection=canonical,
+                operation="execute",
+                params={"sql": sql_clean[:500]},
+                mode="execute",
+                status="dry-run",
+                actor=actor,
+            )
+            raise SystemExit(0)
+        if conn.safety.confirm and not yes:
+            confirm_or_abort(f"Apply SQL to {canonical}?", yes=yes)
+
+    if is_url:
+        from dbctl.runtime import opened_engine
+
+        with opened_engine(ctx, canonical, conn) as stub:
+            _do_execute_ad_hoc(
+                engine=stub.engine,
+                sql=sql_clean,
+                is_select=is_select,
+                output_fmt=output_fmt,
+                canonical=canonical,
+                profile=profile,
+                actor=actor,
+            )
+    else:
+        with opened_conn(ctx, canonical) as (_name, _conn, stub):
+            _do_execute_ad_hoc(
+                engine=stub.engine,
+                sql=sql_clean,
+                is_select=is_select,
+                output_fmt=output_fmt,
+                canonical=canonical,
+                profile=profile,
+                actor=actor,
+            )
+
+
 @main.group("history")
 def history_cmd():
     """Show the audit log."""

{dbctl-0.7.4 → dbctl-0.7.7}/dbctl/runtime.py

@@ -22,6 +22,8 @@ from dbctl.operations import OperationsFileError
 from dbctl.operations import load as load_operations
 
 if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
+
     from dbctl.config import Connection
 
 console = Console()
@@ -72,7 +74,7 @@ def confirm_or_abort(prompt: str, *, yes: bool) -> None:
 class OpenedStub:
     name: str
     conn: Connection
-    engine: object
+    engine: Engine
     tunnel: object
 
 
@@ -85,7 +87,7 @@ def opened_conn(ctx: click.Context, name: str) -> Iterator[tuple[str, Connection
     errors so command callbacks don't need to handle those states.
     """
     from dbctl.connections import resolve
-    from dbctl.db import DBError, build_engine, healthcheck
+    from dbctl.db import DBError, build_engine
     from dbctl.tunnels.base import build_tunnel
 
     conns, _ = registries(ctx)
@@ -108,17 +110,65 @@ def opened_conn(ctx: click.Context, name: str) -> Iterator[tuple[str, Connection
         err_console.print(f"[red]db error:[/red] {e}")
         sys.exit(4)
 
-    if not ctx.obj.get("skip_healthcheck"):
-        ok, _ms, msg = healthcheck(engine, conn.healthcheck.query, conn.healthcheck.timeout_seconds)
-        if not ok:
-            tun.__exit__(None, None, None)
-            err_console.print(f"[red]healthcheck failed:[/red] {msg}")
-            sys.exit(5)
-        if ctx.obj.get("verbose"):
-            console.print(f"[dim]health {canonical}: ok ({_ms:.1f}ms)[/dim]")
-
+    _healthcheck(ctx, canonical, conn, engine, tun)
     stub = OpenedStub(canonical, conn, engine, tun)
     try:
         yield canonical, conn, stub
     finally:
         tun.__exit__(None, None, None)
+
+
+@contextmanager
+def opened_engine(ctx: click.Context, canonical: str, conn: Connection) -> Iterator[OpenedStub]:
+    """Like ``opened_conn`` but takes a pre-built ``Connection`` (instead of
+    resolving a name from the registry). Used by ``dbctl execute`` for
+    inline SQLAlchemy URLs — the connection's ``direct`` block (a
+    placeholder host:port) is unused since ``url:`` overrides it; the
+    tunnel is a no-op ``DirectTunnel`` in that case.
+
+    Yields ``OpenedStub``. Tears the tunnel down on exit. Exits with the
+    same exit-code convention as ``opened_conn`` (3 tunnel, 4 db, 5 health).
+    """
+    from dbctl.db import DBError, build_engine
+    from dbctl.tunnels.base import build_tunnel
+
+    tun = build_tunnel(conn)
+    try:
+        tun.__enter__()
+    except RuntimeError as e:
+        err_console.print(f"[red]tunnel error:[/red] {e}")
+        sys.exit(3)
+    try:
+        engine = build_engine(conn, tun)
+    except DBError as e:
+        tun.__exit__(None, None, None)
+        err_console.print(f"[red]db error:[/red] {e}")
+        sys.exit(4)
+
+    _healthcheck(ctx, canonical, conn, engine, tun)
+    stub = OpenedStub(canonical, conn, engine, tun)
+    try:
+        yield stub
+    finally:
+        tun.__exit__(None, None, None)
+
+
+def _healthcheck(
+    ctx: click.Context,
+    canonical: str,
+    conn: Connection,
+    engine: Engine,
+    tun: object,
+) -> None:
+    """Shared healthcheck prefix for `opened_conn` / `opened_engine`."""
+    from dbctl.db import healthcheck
+
+    if ctx.obj.get("skip_healthcheck"):
+        return
+    ok, ms, msg = healthcheck(engine, conn.healthcheck.query, conn.healthcheck.timeout_seconds)
+    if not ok:
+        tun.__exit__(None, None, None)  # type: ignore[attr-defined]
+        err_console.print(f"[red]healthcheck failed:[/red] {msg}")
+        sys.exit(5)
+    if ctx.obj.get("verbose"):
+        console.print(f"[dim]health {canonical}: ok ({ms:.1f}ms)[/dim]")