dbctl 0.6.2__tar.gz → 0.6.4__tar.gz

{dbctl-0.6.2 → dbctl-0.6.4}/.dbctl/connections.yaml

@@ -226,3 +226,56 @@ connections:
     safety:
       confirm: true
       read_only: true
+
+  # --------------------------------------------------------------------- #
+  # Oracle, SQLite, DuckDB reference templates.
+  # --------------------------------------------------------------------- #
+
+  # Oracle Database — oracledb thin mode (pure Python, no Instant Client).
+  # Use `database:` for the service name (or SID). Healthcheck uses
+  # `SELECT 1 FROM DUAL` which is the Oracle convention.
+  prod-oracle:
+    description: "REFERENCE: Oracle via oracledb thin mode (edit before using)"
+    aliases: []
+    type: direct
+    driver: oracle+oracledb
+    database: ORCLPDB1
+    username: app_admin
+    password: "<set-me>"
+    direct: { host: db.internal, port: 1521 }
+    healthcheck: { query: "SELECT 1 FROM DUAL", timeout_seconds: 10 }
+    safety:
+      confirm: true
+      read_only: true
+
+  # Local SQLite — file-based, no host/port needed (but config schema
+  # requires a `direct:` block). Use `url:` mode for a cleaner config:
+  #   url: "sqlite:////absolute/path/to/mydata.db"
+  local-sqlite:
+    description: "REFERENCE: Local SQLite (edit path before using)"
+    aliases: []
+    type: direct
+    driver: sqlite
+    database: /tmp/mydata.db
+    username: ""
+    password: ""
+    direct: { host: localhost, port: 0 }
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: true
+
+  # Local DuckDB — file-based (or ":memory:" for in-memory analytics).
+  local-duckdb:
+    description: "REFERENCE: Local DuckDB (edit path before using)"
+    aliases: []
+    type: direct
+    driver: duckdb
+    database: /tmp/mydata.duckdb
+    username: ""
+    password: ""
+    direct: { host: localhost, port: 0 }
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: true

{dbctl-0.6.2 → dbctl-0.6.4}/CHANGELOG.md

@@ -5,6 +5,79 @@ 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.6.4] — 2026-08-03
+
+### Added
+
+- **`tunnel open --port`/`-p` flag** — override the local bind port even
+  when the config says `local_port: 0` (auto-pick). Works for `ssm` /
+  `ssh` / `k8s` tunnels (creates a local listener on the chosen port) and
+  `direct` (changes which upstream port SQLAlchemy connects to).
+- **`tunnel test <conn>` subcommand** — opens the tunnel, runs the
+  connection's healthcheck query, then closes the tunnel. Prints
+  `OK <conn> via <type> (host:port) — ok (latency, total)` (green) on
+  success or `FAIL <conn> <stage>: <msg>` (red) on failure. Exit codes
+  match the existing convention: 2 unknown conn, 3 tunnel error, 4 engine
+  error, 5 healthcheck failed.
+- **`tunnel list` subcommand** — lists every configured connection with
+  its tunnel type (`ssm` / `ssh` / `k8s` / `direct`), driver, and key
+  parameters in a rich table. For `ssm`: bastion id/tags, remote
+  host:port, region. For `ssh`: bastion user@host:port, remote
+  host:port. For `k8s`: context, target, namespace, remote port. For
+  `direct`: host:port.
+- **`tunnel` group help** — `dbctl tunnel --help` now explains the four
+  tunnel types (ssm/ssh/k8s/direct) and lists the three subcommands
+  (open/test/list) with one-liner descriptions.
+
+### Changed
+
+- `build_tunnel()` in `dbctl/tunnels/base.py` accepts an optional
+  `override_port` parameter; the CLI `tunnel open --port` flag flows
+  through to it. The override is applied via `model_copy(update=)` so
+  the original config object is not mutated.
+
+## [0.6.3] — 2026-08-03
+
+### Added
+
+- **Oracle Database support** — `oracle+oracledb` driver (thin mode, pure
+  Python — no Oracle Instant Client needed). `oracledb>=2` added as a
+  core dependency. The init wizard offers it in the driver choice list;
+  `_default_port` returns 1521 for Oracle. Native-lib hint for Oracle
+  Instant Client (`libclntsh` / `libociei` / `libocci`) failure path
+  included in `dbctl.db._native_lib_hint`. Healthcheck query convention
+  is `SELECT 1 FROM DUAL`.
+- **SQLite support** — `sqlite` driver (built into Python stdlib, no
+  extra dependency). File-based: `build_engine` skips host/port/
+  username/password injection (just `sqlite:///path`). Config validator
+  exempts file-based drivers (sqlite + duckdb) from the credential
+  requirement — `username` and `password` are not needed.
+- **DuckDB support** — `duckdb` driver. `duckdb>=1` added as a core
+  dependency. Same file-based handling as SQLite (`duckdb:///path` or
+  `duckdb:///:memory:`).
+- **`replay_spec.on_conflict`** field — the conflict-handling strategy
+  for replay mode. Defaults to `skip` (additive — replay new/changed
+  rows without breaking existing entries), unlike `copy_spec` which
+  defaults to `error`. Use `truncate` for a full refresh.
+- **`logo_small.png`** added to top of every `docs/*.md` file; README
+  gets a centred logo_small footer (big logo stays at top).
+
+### Fixed
+
+- **`replay-users` crashed on existing rows** — hardcoded
+  `on_conflict=error` meant any PK collision in the target aborted the
+  replay. Now uses `replay_spec.on_conflict` (default `skip`), so
+  `INSERT IGNORE` / `ON CONFLICT DO NOTHING` handles duplicates cleanly
+  and the report shows inserted vs skipped counts correctly.
+- **File-based drivers (sqlite/duckdb) rejected by config validator**
+  — required username + password even though the drivers ignore them.
+  The validator now exempts `sqlite*` and `duckdb*` from the credential
+  requirement.
+- **File-based drivers: `build_engine` injected host:port into the URL**
+  — SQLAlchemy rejected `sqlite://:***@localhost:0//path` with an
+  ArgumentError. Now skips host/port/username/password for file-based
+  drivers; the URL is just `sqlite:///path`.
+
 ## [0.6.2] — 2026-08-03
 
 ### Added

{dbctl-0.6.2 → dbctl-0.6.4}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: dbctl
-Version: 0.6.2
+Version: 0.6.4
 Summary: Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection.
 Author: dbctl contributors
 License: MIT
-Keywords: cli,database,mssql,mysql,postgres,ssh,ssm,tunnel
+Keywords: cli,database,duckdb,mssql,mysql,oracle,postgres,sqlite,ssh,ssm,tunnel
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -16,6 +16,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Database
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
+Requires-Dist: duckdb>=1
+Requires-Dist: oracledb>=2
 Requires-Dist: psycopg[binary]>=3.1
 Requires-Dist: pydantic>=2
 Requires-Dist: pymysql>=1.1
@@ -85,8 +87,9 @@ your shell history. (For ad-hoc exploration open the tunnel with
 | `direct` | No tunnel — connect to the upstream host:port directly        | none |
 
 Each connection declares its SQLAlchemy URL scheme (`postgresql+psycopg`,
-`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, …), a healthcheck query,
-optional introspection (`info`) queries, and a `safety` policy.
+`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`,
+`sqlite`, `duckdb`, …), a healthcheck query, optional introspection
+(`info`) queries, and a `safety` policy.
 
 Operations are declared separately in `operations.yaml`. Each operation is a
 parameterised SQL block (using `$name` placeholders) with declared parameters;
@@ -192,6 +195,9 @@ dbctl pg history                               # per-connection audit log
 dbctl pg again                                 # re-run last op on pg
 
 dbctl tunnel open pg                           # hold tunnel for ad-hoc psql
+dbctl tunnel open pg --port 15432              # override the local bind port
+dbctl tunnel test pg                           # open + healthcheck + close, report OK/FAIL
+dbctl tunnel list                              # list all connections + tunnel info
 ```
 
 > SQL Server needs an installed ODBC driver on the host (`ODBC Driver 18 for

{dbctl-0.6.2 → dbctl-0.6.4}/README.md

@@ -53,8 +53,9 @@ your shell history. (For ad-hoc exploration open the tunnel with
 | `direct` | No tunnel — connect to the upstream host:port directly        | none |
 
 Each connection declares its SQLAlchemy URL scheme (`postgresql+psycopg`,
-`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, …), a healthcheck query,
-optional introspection (`info`) queries, and a `safety` policy.
+`mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`,
+`sqlite`, `duckdb`, …), a healthcheck query, optional introspection
+(`info`) queries, and a `safety` policy.
 
 Operations are declared separately in `operations.yaml`. Each operation is a
 parameterised SQL block (using `$name` placeholders) with declared parameters;
@@ -160,6 +161,9 @@ dbctl pg history                               # per-connection audit log
 dbctl pg again                                 # re-run last op on pg
 
 dbctl tunnel open pg                           # hold tunnel for ad-hoc psql
+dbctl tunnel open pg --port 15432              # override the local bind port
+dbctl tunnel test pg                           # open + healthcheck + close, report OK/FAIL
+dbctl tunnel list                              # list all connections + tunnel info
 ```
 
 > SQL Server needs an installed ODBC driver on the host (`ODBC Driver 18 for

{dbctl-0.6.2 → dbctl-0.6.4}/dbctl/cli.py

@@ -1279,13 +1279,36 @@ def history_show(ctx, run_id):
 
 @main.group("tunnel")
 def tunnel_cmd():
-    """Hold a tunnel open for ad-hoc work."""
+    """Open, test, or list database tunnels.
+
+    \b
+    Tunnels connect dbctl to databases that aren't directly reachable:
+    - ssm:    AWS SSM port-forward through an EC2 bastion
+    - ssh:    Classic ssh -N -L port-forward through a bastion
+    - k8s:    kubectl port-forward to a Service or Pod
+    - direct: No tunnel — connect to upstream host:port
+
+    \b
+    Subcommands:
+    - tunnel open <conn> [--port N]   Hold a tunnel open for ad-hoc work
+    - tunnel test <conn>               Open + healthcheck + close, report OK/FAIL
+    - tunnel list                      List all connections with tunnel info
+    """
 
 
 @tunnel_cmd.command("open")
 @click.argument("name")
+@click.option(
+    "-p",
+    "--port",
+    "port",
+    type=click.INT,
+    default=None,
+    help="Override the local bind port (even if config says 0 = auto).",
+)
 @click.pass_context
-def tunnel_open(ctx, name):
+def tunnel_open(ctx, name, port):
+    """Hold a tunnel open for ad-hoc work (Ctrl-C to close)."""
     from dbctl.connections import resolve
 
     conns, _ = registries(ctx)
@@ -1296,8 +1319,12 @@ def tunnel_open(ctx, name):
         raise SystemExit(2)
     from dbctl.tunnels.base import build_tunnel
 
-    tun = build_tunnel(c)
-    tun.__enter__()
+    tun = build_tunnel(c, override_port=port)
+    try:
+        tun.__enter__()
+    except RuntimeError as e:
+        err_console.print(f"[red]tunnel error:[/red] {e}")
+        raise SystemExit(3)
     console.print(f"[green]tunnel open:[/green] {tun.local_host}:{tun.local_port} -> {canonical}")
     console.print("[dim]Ctrl-C to close...[/dim]")
     try:
@@ -1309,6 +1336,102 @@ def tunnel_open(ctx, name):
         tun.__exit__(None, None, None)
 
 
+@tunnel_cmd.command("test")
+@click.argument("name")
+@click.pass_context
+def tunnel_test(ctx, name):
+    """Open the tunnel, run the healthcheck, and close it. Reports OK or FAIL."""
+    from dbctl.connections import resolve
+    from dbctl.db import build_engine, healthcheck
+    from dbctl.tunnels.base import build_tunnel
+
+    conns, _ = registries(ctx)
+    try:
+        canonical, c = resolve(name, conns)
+    except KeyError as e:
+        err_console.print(f"[red]{e}[/red]")
+        raise SystemExit(2)
+
+    tun = build_tunnel(c)
+    started = time.monotonic()
+    try:
+        tun.__enter__()
+    except RuntimeError as e:
+        elapsed = (time.monotonic() - started) * 1000
+        err_console.print(f"[red]FAIL[/red] {canonical} tunnel: {e} ({elapsed:.0f}ms)")
+        raise SystemExit(3)
+
+    try:
+        engine = build_engine(c, tun)
+    except Exception as e:  # noqa: BLE001 - DBError, ImportError, etc.
+        tun.__exit__(None, None, None)
+        elapsed = (time.monotonic() - started) * 1000
+        err_console.print(f"[red]FAIL[/red] {canonical} engine: {e} ({elapsed:.0f}ms)")
+        raise SystemExit(4)
+
+    ok, latency_ms, msg = healthcheck(engine, c.healthcheck.query, c.healthcheck.timeout_seconds)
+    tun.__exit__(None, None, None)
+    total_ms = (time.monotonic() - started) * 1000
+
+    if ok:
+        console.print(
+            f"[green]OK[/green] {canonical} via {c.type.value} "
+            f"({tun.local_host}:{tun.local_port}) — {msg} ({latency_ms:.1f}ms, total {total_ms:.0f}ms)"
+        )
+    else:
+        err_console.print(f"[red]FAIL[/red] {canonical} healthcheck: {msg} ({total_ms:.0f}ms)")
+        raise SystemExit(5)
+
+
+@tunnel_cmd.command("list")
+@click.pass_context
+def tunnel_list(ctx):
+    """List all connections with their tunnel type and key parameters."""
+    conns, _ = registries(ctx)
+    if not conns:
+        console.print("[dim]no connections configured[/dim]")
+        return
+
+    from rich.table import Table as _Table
+
+    table = _Table(title="tunnels", header_style="bold cyan")
+    table.add_column("name")
+    table.add_column("type")
+    table.add_column("driver")
+    table.add_column("info")
+
+    for name, c in sorted(conns.items()):
+        ttype = c.type.value
+        driver = c.driver or "(from url)"
+        info_parts = []
+        if ttype == "direct":
+            assert c.direct
+            info_parts.append(f"host={c.direct.host}:{c.direct.port}")
+        elif ttype == "ssm":
+            assert c.ssm
+            if c.ssm.bastion_instance_id:
+                info_parts.append(f"bastion={c.ssm.bastion_instance_id}")
+            elif c.ssm.bastion_tags:
+                info_parts.append(f"bastion_tags={dict(c.ssm.bastion_tags)}")
+            info_parts.append(f"remote={c.ssm.remote_host}:{c.ssm.remote_port}")
+            if c.ssm.region:
+                info_parts.append(f"region={c.ssm.region}")
+        elif ttype == "ssh":
+            assert c.ssh
+            info_parts.append(f"bastion={c.ssh.user}@{c.ssh.host}:{c.ssh.port}")
+            info_parts.append(f"remote={c.ssh.remote_host}:{c.ssh.remote_port}")
+        elif ttype == "k8s":
+            assert c.k8s
+            info_parts.append(f"context={c.k8s.context}")
+            info_parts.append(f"target={c.k8s.target}")
+            if c.k8s.namespace:
+                info_parts.append(f"ns={c.k8s.namespace}")
+            info_parts.append(f"port={c.k8s.remote_port}")
+        table.add_row(name, ttype, driver, ", ".join(info_parts))
+
+    console.print(table)
+
+
 # --------------------------------------------------------------------------- #
 # dashboard + history rendering
 # --------------------------------------------------------------------------- #

{dbctl-0.6.2 → dbctl-0.6.4}/dbctl/config.py

@@ -247,16 +247,22 @@ class Connection(BaseModel):
         if not self.database:
             raise ValueError("'database' is required (or use 'url:' for a full connection string)")
 
+        # File-based drivers (sqlite, duckdb) have no auth — skip the
+        # credential requirement entirely. The username/password fields
+        # are accepted (and ignored by the driver) for config-schema
+        # compatibility, but none is required.
+        _file_based = self.driver.startswith(("sqlite", "duckdb"))
+
         sources = [bool(self.password), bool(self.password_env), self.prompt]
         if sum(sources) > 1:
             raise ValueError("'password', 'password_env' and 'prompt' are mutually exclusive")
-        if not any(sources) and not self.windows_sso:
+        if not _file_based and not any(sources) and not self.windows_sso:
             raise ValueError("set 'password', 'password_env', 'prompt: true', or 'windows_sso: true'")
         if self.windows_sso and any(sources):
             raise ValueError("'windows_sso' is mutually exclusive with password/password_env/prompt")
         if self.windows_sso and not self.driver.startswith("mssql"):
             raise ValueError("'windows_sso' is only supported with mssql+pyodbc driver")
-        if not self.windows_sso and not self.username:
+        if not _file_based and not self.windows_sso and not self.username:
             raise ValueError("'username' is required (or set 'windows_sso: true' for mssql SSO)")
         return self
 
@@ -339,11 +345,17 @@ class ReplaySpec(BaseModel):
     ``package.module:callable`` / ``package.module.callable`` resolving to a
     ``Callable[[dict], dict]``. The callable runs in-process; it must not
     reach across connections.
+
+    `on_conflict` defaults to ``skip`` (unlike ``copy`` which defaults to
+    ``error``) — a replay is typically additive (replay new/changed rows
+    from a source log into a target without breaking existing entries).
+    Use ``truncate`` if you want a full refresh instead.
     """
 
     model_config = ConfigDict(extra="forbid")
     batch_size: int = 10000
     tables: list[str] | None = None  # None = introspect src
+    on_conflict: OnConflict = OnConflict.skip  # default skip (additive)
     where: dict[str, str] = Field(default_factory=dict)
     transform: str = "identity"
 

{dbctl-0.6.2 → dbctl-0.6.4}/dbctl/db.py

@@ -80,14 +80,12 @@ def _connect_args(conn: Connection, timeout: float) -> dict:
     """Driver-specific connect-time knobs (mainly connect_timeout)."""
     args: dict = {}
     driver = _driver_name(conn)
-    if driver.startswith(("postgresql", "mysql", "mariadb")):
+    if driver.startswith(("postgresql", "mysql", "mariadb", "oracle")):
         args["connect_timeout"] = int(max(1, timeout))
+    # sqlite + duckdb are file-based — no connect_timeout; SQLAlchemy
+    # ignores it anyway, but we skip it so we don't pass an unknown kwarg
+    # to the underlying C library.
     if conn.windows_sso:
-        # pyodbc: Trusted_Connection=yes tells the ODBC driver to use the
-        # current Windows user's credentials (Kerberos / NTLM). The ODBC
-        # Driver 17+ also supports Authentication=ActiveDirectoryIntegrated
-        # for Azure AD SSO — use that by setting it explicitly via
-        # connect_args in your config if needed.
         args["Trusted_Connection"] = "yes"
     return args
 
@@ -99,6 +97,11 @@ def build_engine(conn: Connection, tunnel: Tunnel, *, echo: bool = False) -> Eng
     tunnel's local bind is NOT injected — the URL's own host:port wins. This
     is intentional: a user who provides a full URL is taking responsibility
     for the entire connection string.
+
+    File-based drivers (``sqlite``, ``duckdb``) never get host/port/username/
+    password injected — the URL is just ``driver:///path/to/file``. The
+    tunnel's local bind is irrelevant for file-based DBs (the file is
+    local), and injecting `host:port` makes SQLAlchemy reject the URL.
     """
     driver = _driver_name(conn)
     _check_driver_available(driver)
@@ -107,6 +110,11 @@ def build_engine(conn: Connection, tunnel: Tunnel, *, echo: bool = False) -> Eng
 
     if conn.url:
         url = make_url(conn.url)
+    elif driver.startswith(("sqlite", "duckdb")):
+        # File-based: URL is just "sqlite:///path" or "duckdb:///path".
+        # No host/port/username/password — those are meaningless for a
+        # local file. The database field IS the file path.
+        url = URL.create(driver, database=conn.database)
     else:
         password = resolve_password(conn)
         url = URL.create(
@@ -138,6 +146,9 @@ def _check_driver_available(driver: str) -> None:
         "mysql+pymysql": "pymysql",
         "mariadb+pymysql": "pymysql",
         "mssql+pyodbc": "pyodbc",
+        "oracle+oracledb": "oracledb",
+        "sqlite": "sqlite3",  # stdlib — always available
+        "duckdb": "duckdb",
     }
     pkg = module_map.get(driver)
     if pkg is None:
@@ -183,6 +194,12 @@ def _native_lib_hint(driver: str, library: str) -> str:
             "(Debian/Ubuntu: `sudo apt install libpq5`, "
             "RHEL/Fedora: `sudo dnf install libpq`, macOS: `brew install libpq`)."
         )
+    if "libociei" in (library or "") or "libclntsh" in (library or "") or "libocci" in (library or ""):
+        return (
+            "missing Oracle Instant Client libs (libclntsh / libociei / libocci); "
+            "install Oracle Instant Client (download from oracle.com, or use "
+            "`pip install oracledb` with the default Thin mode which needs no native libs)."
+        )
     return ""
 
 

{dbctl-0.6.2 → dbctl-0.6.4}/dbctl/init.py

@@ -67,7 +67,15 @@ def run_wizard(*, profile: str | None) -> None:
         driver = click.prompt(
             "driver (sqlalchemy url scheme)",
             type=click.Choice(
-                ["postgresql+psycopg", "mysql+pymysql", "mariadb+pymysql", "mssql+pyodbc"],
+                [
+                    "postgresql+psycopg",
+                    "mysql+pymysql",
+                    "mariadb+pymysql",
+                    "mssql+pyodbc",
+                    "oracle+oracledb",
+                    "sqlite",
+                    "duckdb",
+                ],
                 case_sensitive=False,
             ),
             default="postgresql+psycopg",
@@ -214,6 +222,8 @@ def _default_port(driver: str) -> int:
         return 3306
     if driver.startswith("mssql"):
         return 1433
+    if driver.startswith("oracle"):
+        return 1521
     return 5432
 
 

{dbctl-0.6.2 → dbctl-0.6.4}/dbctl/multi.py

@@ -672,14 +672,14 @@ def run_replay(
     each row before it lands in the insert batch. ``"identity"`` makes the
     replay equivalent to a plain copy.
     """
-    from dbctl.config import CopySpec, OnConflict
+    from dbctl.config import CopySpec
 
     # Adapt ReplaySpec → CopySpec so we reuse the copy machinery verbatim.
     copy_spec = CopySpec(
         batch_size=spec.batch_size,
         tables=spec.tables,
         where=spec.where,
-        on_conflict=OnConflict.error,  # replay is copy-with-transform; default to no skip
+        on_conflict=spec.on_conflict,  # replay defaults to skip (additive)
     )
     transform = _resolve_transform(spec.transform)
     return run_copy(

{dbctl-0.6.2 → dbctl-0.6.4}/dbctl/tunnels/base.py

@@ -49,24 +49,40 @@ def _terminate(proc: subprocess.Popen) -> None:
             proc.wait(timeout=5)
 
 
-def build_tunnel(conn: Connection) -> Tunnel:
+def build_tunnel(conn: Connection, *, override_port: int | None = None) -> Tunnel:
+    """Construct a Tunnel for the connection's type.
+
+    ``override_port`` lets the CLI (e.g. ``tunnel open --port 1234``) pin
+    the local bind port even when the config says ``local_port: 0`` (auto).
+    For ``direct`` tunnels the override replaces the upstream port (useful
+    for pointing at a different port than the config declares).
+    """
     from dbctl.tunnels.direct import DirectTunnel as _Direct
-    from dbctl.tunnels.k8s import K8sTunnel as _K8s
+    from dbctl.tunnels.k8s import K8sTunnel as _K8k
     from dbctl.tunnels.ssh import SshTunnel as _Ssh
     from dbctl.tunnels.ssm import SsmTunnel as _Ssm
 
     match conn.type.value:
         case "ssm":
             assert conn.ssm
+            if override_port is not None:
+                # Mutate a copy so the original config is untouched.
+                conn.ssm = conn.ssm.model_copy(update={"local_port": override_port})
             return _Ssm(conn.ssm)
         case "ssh":
             assert conn.ssh
+            if override_port is not None:
+                conn.ssh = conn.ssh.model_copy(update={"local_port": override_port})
             return _Ssh(conn.ssh)
         case "k8s":
             assert conn.k8s
-            return _K8s(conn.k8s)
+            if override_port is not None:
+                conn.k8s = conn.k8s.model_copy(update={"local_port": override_port})
+            return _K8k(conn.k8s)
         case "direct":
             assert conn.direct
+            if override_port is not None:
+                conn.direct = conn.direct.model_copy(update={"port": override_port})
             return _Direct(conn.direct)
         case _:  # pragma: no cover - exhaustive
             raise ValueError(f"unknown tunnel type {conn.type!r}")

{dbctl-0.6.2 → dbctl-0.6.4}/docs/connections.md

@@ -39,7 +39,7 @@ overlap with a clear message.
 | `description`   | string                                    | no       | shown in the dashboard and `dbctl connections list`. |
 | `aliases`       | list of strings                           | no       | alternates that resolve back to this connection (e.g. `prod` → `db1`). |
 | `type`          | `ssm` \| `ssh` \| `k8s` \| `direct`       | **yes**  | selects the tunnel implementation. |
-| `driver`        | string                                    | **yes**  | SQLAlchemy URL scheme. Supported: `postgresql+psycopg`, `mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`. Any other SQLAlchemy scheme works as long as its driver is importable. |
+| `driver`        | string                                    | **yes**  | SQLAlchemy URL scheme. Supported: `postgresql+psycopg`, `mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`, `sqlite`, `duckdb`. Any other SQLAlchemy scheme works as long as its driver is importable. |
 | `database`      | string                                    | **yes**  | database / catalog name passed to SQLAlchemy. |
 | `username`      | string                                    | **yes** (unless `windows_sso`) | DB user. |
 | `password`      | string                                    | see rule | plaintext DB password (local dev only — don't commit real secrets to YAML). Mutually exclusive with `password_env`, `prompt`, and `windows_sso`. |
@@ -320,6 +320,72 @@ connections:
     safety: { confirm: false, read_only: false }
 ```
 
+### Oracle Database (thin mode — no native client needed)
+
+```yaml
+connections:
+  prod-oracle:
+    description: "Production Oracle (oracledb thin mode)"
+    type: direct
+    driver: oracle+oracledb
+    database: ORCLPDB1   # service name (or SID)
+    username: app_admin
+    password_env: DBCTL_ORACLE_PASSWORD
+    direct: { host: db.internal, port: 1521 }
+    healthcheck: { query: "SELECT 1 FROM DUAL", timeout_seconds: 10 }
+    safety:
+      confirm: true
+      read_only: false
+```
+
+> `oracledb` defaults to **thin mode** (pure Python, no Oracle Instant
+> Client needed). If you need thick mode (native Oracle client libs), set
+> it via the `url:` field with `thick_mode=true` in the query string.
+
+### Local SQLite database (file-based)
+
+```yaml
+connections:
+  local-sqlite:
+    description: "Local SQLite database"
+    type: direct
+    driver: sqlite
+    database: /path/to/mydata.db   # absolute path to the .db file
+    username: ""                   # sqlite ignores these but config requires one
+    password: ""                   # sqlite ignores
+    direct: { host: localhost, port: 0 }  # ignored by sqlite; required by config schema
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: false
+```
+
+> SQLite and DuckDB are file-based — the `host` / `port` fields are
+> ignored by the driver but `type: direct` still requires a `direct:`
+> block. Use `url:` mode if you prefer:
+> ```yaml
+> url: "sqlite:////absolute/path/to/mydata.db"
+> ```
+> (Note the four slashes for absolute paths in SQLAlchemy's sqlite scheme.)
+
+### Local DuckDB database (file-based)
+
+```yaml
+connections:
+  local-duckdb:
+    description: "Local DuckDB database"
+    type: direct
+    driver: duckdb
+    database: /path/to/mydata.duckdb   # or ":memory:" for in-memory
+    username: ""                        # duckdb ignores
+    password: ""                        # duckdb ignores
+    direct: { host: localhost, port: 0 }
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: false
+```
+
 ### CloudNativePG cluster via kubectl port-forward
 
 ```yaml

{dbctl-0.6.2 → dbctl-0.6.4}/docs/tutorial.md

@@ -585,6 +585,15 @@ tunnel open: 127.0.0.1:5433 -> pg
 Ctrl-C to close...
 ```
 
+Override the local port with `--port` (even if the config says `local_port: 0`
+= auto-pick):
+
+```bash
+▶ uv run dbctl tunnel open pg --port 15432
+tunnel open: 127.0.0.1:15432 -> pg
+Ctrl-C to close...
+```
+
 In another shell, use that local bind with your favourite client:
 
 ```bash
@@ -594,6 +603,28 @@ PGPASSWORD=$DBCTL_PG_PASSWORD psql -h 127.0.0.1 -p 5433 -U app_admin -d app
 The tunnel is torn down cleanly when you Ctrl-C the `dbctl tunnel open`
 process — an `atexit` fallback covers hard kills.
 
+### `tunnel test` — open + healthcheck + close
+
+```bash
+▶ uv run dbctl tunnel test pg
+OK pg via direct (127.0.0.1:5433) — ok (31.2ms, total 185ms)
+```
+
+Opens the tunnel, runs the connection's healthcheck query, then closes the
+tunnel. Prints `OK` (green) with latency on success, or `FAIL` (red) with
+a clean error message on failure. Exit codes: 0 success, 2 unknown conn,
+3 tunnel error, 4 engine error, 5 healthcheck failed.
+
+### `tunnel list` — show all tunnels at a glance
+
+```bash
+▶ uv run dbctl tunnel list
+```
+
+Lists every configured connection with its tunnel type (`ssm`/`ssh`/`k8s`/
+`direct`), driver, and key parameters (bastion, remote host, port, region,
+context/namespace for k8s).
+
 ---
 
 ## 14. Use `dbctl init` to add the next connection

{dbctl-0.6.2 → dbctl-0.6.4}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dbctl"
-version = "0.6.2"
+version = "0.6.4"
 description = "Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection."
 readme = "README.md"
 requires-python = ">=3.12"
 license = { text = "MIT" }
 authors = [{ name = "dbctl contributors" }]
-keywords = ["cli", "database", "postgres", "mysql", "mssql", "ssm", "ssh", "tunnel"]
+keywords = ["cli", "database", "postgres", "mysql", "mssql", "oracle", "sqlite", "duckdb", "ssm", "ssh", "tunnel"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -31,6 +31,8 @@ dependencies = [
   "psycopg[binary]>=3.1",
   "pymysql>=1.1",
   "pyodbc>=5",
+  "oracledb>=2",
+  "duckdb>=1",
 ]
 
 [project.optional-dependencies]