dbctl 0.7.2__tar.gz → 0.7.3__tar.gz

{dbctl-0.7.2 → dbctl-0.7.3}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.3] — 2026-08-04
+
+### Added
+
+- **`azure` tunnel type** — reaches a VM through Azure Bastion via
+  `az network bastion tunnel` (requires the Bastion resource on the
+  Standard SKU). New `AzureBastionTunnel` connection block
+  (`resource_group` / `bastion_name` / `target_resource_id` /
+  `subscription` / `remote_port` / `local_port`), same lifecycle
+  (subprocess + `atexit` cleanup, `local_port: 0` auto-pick) as the
+  existing `ssm` / `ssh` / `k8s` tunnels. Shells out to the `az` CLI —
+  no Azure SDK dependency.
+- **`gcp` tunnel type** — reaches a Compute Engine instance through
+  Identity-Aware Proxy via `gcloud compute start-iap-tunnel` (requires
+  IAP TCP forwarding on the instance's network and the
+  `roles/iap.tunnelResourceAccessor` IAM role). New `GcpIapTunnel`
+  connection block (`project` / `zone` / `instance` / `remote_port` /
+  `local_port`). Shells out to the `gcloud` CLI — no GCP SDK dependency.
+- Both new types are wired into `dbctl doctor` (reports `az`/`gcloud` on
+  `PATH`, only flagged `required` when a configured connection actually
+  uses them), `dbctl tunnel list`, and the `dbctl init` wizard.
+
 ## [0.7.2] — 2026-08-04
 
 ### Added

{dbctl-0.7.2 → dbctl-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbctl
-Version: 0.7.2
+Version: 0.7.3
 Summary: Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection.
 Author: dbctl contributors
 License: MIT
@@ -85,6 +85,8 @@ your shell history. (For ad-hoc exploration open the tunnel with
 | `ssh`    | Classic `ssh -N -L` port-forward through a bastion             | `ssh` CLI on PATH, an SSH key file |
 | `k8s`    | `kubectl port-forward` to a Service / Pod in a cluster         | `kubectl` CLI on PATH, a valid kubeconfig |
 | `direct` | No tunnel — connect to the upstream host:port directly        | none |
+| `azure`  | Azure Bastion tunnel to a VM (`az network bastion tunnel`)     | `az` CLI on PATH, active `az login` session, Bastion on Standard SKU |
+| `gcp`    | IAP TCP tunnel to a Compute Engine instance (`gcloud compute start-iap-tunnel`) | `gcloud` CLI on PATH, active `gcloud auth login` session |
 
 Each connection declares its SQLAlchemy URL scheme (`postgresql+psycopg`,
 `mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`,
@@ -145,9 +147,11 @@ uv pip install -e .
 uv run dbctl --help
 ```
 
-The `aws` and `ssh` binaries are expected on `PATH`. No `boto3`, no
-`paramiko` — dbctl always shells out so you keep your existing SSO session,
-key agents, and MFA flows.
+The `aws`, `ssh`, `az`, and `gcloud` binaries are expected on `PATH` (only
+the ones your configured tunnel types actually need — `dbctl doctor` tells
+you which). No `boto3`, no `paramiko`, no Azure/GCP SDKs — dbctl always
+shells out so you keep your existing SSO session, key agents, and MFA
+flows.
 
 ## Quick start with the bundled docker-compose fleet
 

{dbctl-0.7.2 → dbctl-0.7.3}/README.md

@@ -51,6 +51,8 @@ your shell history. (For ad-hoc exploration open the tunnel with
 | `ssh`    | Classic `ssh -N -L` port-forward through a bastion             | `ssh` CLI on PATH, an SSH key file |
 | `k8s`    | `kubectl port-forward` to a Service / Pod in a cluster         | `kubectl` CLI on PATH, a valid kubeconfig |
 | `direct` | No tunnel — connect to the upstream host:port directly        | none |
+| `azure`  | Azure Bastion tunnel to a VM (`az network bastion tunnel`)     | `az` CLI on PATH, active `az login` session, Bastion on Standard SKU |
+| `gcp`    | IAP TCP tunnel to a Compute Engine instance (`gcloud compute start-iap-tunnel`) | `gcloud` CLI on PATH, active `gcloud auth login` session |
 
 Each connection declares its SQLAlchemy URL scheme (`postgresql+psycopg`,
 `mysql+pymysql`, `mariadb+pymysql`, `mssql+pyodbc`, `oracle+oracledb`,
@@ -111,9 +113,11 @@ uv pip install -e .
 uv run dbctl --help
 ```
 
-The `aws` and `ssh` binaries are expected on `PATH`. No `boto3`, no
-`paramiko` — dbctl always shells out so you keep your existing SSO session,
-key agents, and MFA flows.
+The `aws`, `ssh`, `az`, and `gcloud` binaries are expected on `PATH` (only
+the ones your configured tunnel types actually need — `dbctl doctor` tells
+you which). No `boto3`, no `paramiko`, no Azure/GCP SDKs — dbctl always
+shells out so you keep your existing SSO session, key agents, and MFA
+flows.
 
 ## Quick start with the bundled docker-compose fleet
 

{dbctl-0.7.2 → dbctl-0.7.3}/dbctl/cli.py

@@ -1289,6 +1289,8 @@ def _doctor_deps(ctx, conns) -> None:
         ("kubectl", TunnelType.k8s, "install: https://kubernetes.io/docs/tasks/tools/"),
         ("aws", TunnelType.ssm, "install: `pip install awscli` or your OS package"),
         ("ssh", TunnelType.ssh, "install: OpenSSH client (openssh-clients / openssh-client)"),
+        ("az", TunnelType.azure, "install: https://learn.microsoft.com/cli/azure/install-azure-cli"),
+        ("gcloud", TunnelType.gcp, "install: https://cloud.google.com/sdk/docs/install"),
     ]
 
     dep_table = Table(title="optional dependencies", header_style="bold cyan")
@@ -1367,6 +1369,8 @@ def tunnel_cmd():
     - 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
+    - azure:  Azure Bastion tunnel to a VM (az network bastion tunnel)
+    - gcp:    GCP IAP TCP tunnel to a Compute Engine instance (gcloud compute start-iap-tunnel)
 
     \b
     Subcommands:
@@ -1507,6 +1511,18 @@ def tunnel_list(ctx):
             if c.k8s.namespace:
                 info_parts.append(f"ns={c.k8s.namespace}")
             info_parts.append(f"port={c.k8s.remote_port}")
+        elif ttype == "azure":
+            assert c.azure
+            info_parts.append(f"bastion={c.azure.bastion_name}")
+            info_parts.append(f"target={c.azure.target_resource_id}")
+            info_parts.append(f"port={c.azure.remote_port}")
+        elif ttype == "gcp":
+            assert c.gcp
+            info_parts.append(f"instance={c.gcp.instance}")
+            info_parts.append(f"zone={c.gcp.zone}")
+            if c.gcp.project:
+                info_parts.append(f"project={c.gcp.project}")
+            info_parts.append(f"port={c.gcp.remote_port}")
         table.add_row(name, ttype, driver, ", ".join(info_parts))
 
     console.print(table)

{dbctl-0.7.2 → dbctl-0.7.3}/dbctl/config.py

@@ -26,6 +26,8 @@ class TunnelType(StrEnum):
     ssh = "ssh"
     k8s = "k8s"
     direct = "direct"
+    azure = "azure"
+    gcp = "gcp"
 
 
 class OpScope(StrEnum):
@@ -146,6 +148,37 @@ class DirectTunnel(BaseModel):
     port: int = 5432
 
 
+class AzureBastionTunnel(BaseModel):
+    """Azure Bastion tunnel via ``az network bastion tunnel`` subprocess.
+
+    Requires an Azure Bastion resource on the Standard SKU (native client
+    support / tunnel command needs Standard, not Basic) in the target VM's
+    VNet.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+    resource_group: str
+    bastion_name: str
+    target_resource_id: str  # full ARM resource id of the target VM
+    subscription: str | None = None  # az CLI --subscription (name or id)
+    remote_port: int = 5432  # --resource-port on the target VM
+    local_port: int = 0  # 0 = auto-pick free port
+
+
+class GcpIapTunnel(BaseModel):
+    """GCP Identity-Aware Proxy TCP tunnel via ``gcloud compute
+    start-iap-tunnel`` subprocess. Requires IAP TCP forwarding enabled on
+    the target instance's network and the caller to have the
+    ``roles/iap.tunnelResourceAccessor`` IAM role."""
+
+    model_config = ConfigDict(extra="forbid")
+    project: str | None = None  # gcloud --project; omit to use the CLI's active project
+    zone: str
+    instance: str
+    remote_port: int = 5432  # port on the instance to forward
+    local_port: int = 0  # 0 = auto-pick free port
+
+
 # --------------------------------------------------------------------------- #
 # info / healthcheck
 # --------------------------------------------------------------------------- #
@@ -194,6 +227,8 @@ class Connection(BaseModel):
     ssh: SshTunnel | None = None
     k8s: K8sTunnel | None = None
     direct: DirectTunnel | None = None
+    azure: AzureBastionTunnel | None = None
+    gcp: GcpIapTunnel | None = None
 
     healthcheck: Healthcheck = Field(default_factory=Healthcheck)
     info: list[InfoQuery] = Field(default_factory=list)
@@ -214,6 +249,12 @@ class Connection(BaseModel):
             case TunnelType.direct:
                 if self.direct is None:
                     raise ValueError("'direct' block required when type=direct")
+            case TunnelType.azure:
+                if self.azure is None:
+                    raise ValueError("'azure' block required when type=azure")
+            case TunnelType.gcp:
+                if self.gcp is None:
+                    raise ValueError("'gcp' block required when type=gcp")
 
         if self.url is not None:
             # Full-URL mode: driver/database/username/password fields are all

{dbctl-0.7.2 → dbctl-0.7.3}/dbctl/init.py

@@ -12,8 +12,10 @@ import yaml
 from rich.console import Console
 
 from dbctl.config import (
+    AzureBastionTunnel,
     Connection,
     DirectTunnel,
+    GcpIapTunnel,
     Healthcheck,
     K8sTunnel,
     SshTunnel,
@@ -44,7 +46,7 @@ def run_wizard(*, profile: str | None) -> None:
         default=False,
     )
 
-    ssm = ssh = k8s = direct = None
+    ssm = ssh = k8s = direct = azure = gcp = None
     url = None
     driver = None
     database = None
@@ -113,6 +115,10 @@ def run_wizard(*, profile: str | None) -> None:
             ssh = _ask_ssh()
         elif type_ == "k8s":
             k8s = _ask_k8s()
+        elif type_ == "azure":
+            azure = _ask_azure()
+        elif type_ == "gcp":
+            gcp = _ask_gcp()
         else:
             host = click.prompt("host", default="localhost")
             port = click.prompt("port", type=int, default=_default_port(driver or ""))
@@ -138,6 +144,8 @@ def run_wizard(*, profile: str | None) -> None:
         ssh=ssh,
         k8s=k8s,
         direct=direct,
+        azure=azure,
+        gcp=gcp,
         healthcheck=healthcheck,
         safety={"confirm": confirm, "read_only": read_only},
     )
@@ -215,6 +223,38 @@ def _ask_k8s() -> K8sTunnel:
     )
 
 
+def _ask_azure() -> AzureBastionTunnel:
+    resource_group = click.prompt("resource group", type=str)
+    bastion_name = click.prompt("bastion name", type=str)
+    target_resource_id = click.prompt("target VM resource id (full ARM resource id)", type=str)
+    subscription = click.prompt("azure subscription (name or id, optional)", default="")
+    remote_port = click.prompt("remote port (on the target VM)", type=int, default=5432)
+    local_port = click.prompt("local port (0 = auto)", type=int, default=0)
+    return AzureBastionTunnel(
+        resource_group=resource_group,
+        bastion_name=bastion_name,
+        target_resource_id=target_resource_id,
+        subscription=subscription or None,
+        remote_port=remote_port,
+        local_port=local_port,
+    )
+
+
+def _ask_gcp() -> GcpIapTunnel:
+    project = click.prompt("gcp project (optional; blank = gcloud's active project)", default="")
+    zone = click.prompt("zone", type=str)
+    instance = click.prompt("instance name", type=str)
+    remote_port = click.prompt("remote port (on the instance)", type=int, default=5432)
+    local_port = click.prompt("local port (0 = auto)", type=int, default=0)
+    return GcpIapTunnel(
+        project=project or None,
+        zone=zone,
+        instance=instance,
+        remote_port=remote_port,
+        local_port=local_port,
+    )
+
+
 def _default_port(driver: str) -> int:
     if driver.startswith("postgresql"):
         return 5432

dbctl-0.7.3/dbctl/tunnels/azure.py

@@ -0,0 +1,81 @@
+"""Azure Bastion tunnel via the ``az`` CLI subprocess."""
+
+from __future__ import annotations
+
+import atexit
+import shutil
+import subprocess
+
+from dbctl.config import AzureBastionTunnel as _Conn
+from dbctl.tunnels.base import _terminate, find_free_port, wait_local_open
+
+
+class AzureBastionTunnel:
+    def __init__(self, conn: _Conn) -> None:
+        self.conn = conn
+        self.local_host = "127.0.0.1"
+        self.local_port = conn.local_port or find_free_port()
+        self._proc: subprocess.Popen | None = None
+
+    def __enter__(self) -> int:
+        # On Windows the Azure CLI installs as `az.cmd`, not `az.exe` —
+        # subprocess.Popen(["az", ...]) without shell=True raises
+        # FileNotFoundError even though `az` is genuinely on PATH, because
+        # CreateProcess won't resolve a bare command name to a .cmd/.bat
+        # launcher. Resolving the full path via shutil.which first fixes
+        # this on Windows and is a no-op on Linux/macOS (real executable).
+        cmd = [
+            shutil.which("az") or "az",
+            "network",
+            "bastion",
+            "tunnel",
+            "--name",
+            self.conn.bastion_name,
+            "--resource-group",
+            self.conn.resource_group,
+            "--target-resource-id",
+            self.conn.target_resource_id,
+            "--resource-port",
+            str(self.conn.remote_port),
+            "--port",
+            str(self.local_port),
+        ]
+        if self.conn.subscription:
+            cmd += ["--subscription", self.conn.subscription]
+
+        try:
+            self._proc = subprocess.Popen(
+                cmd,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+                stdin=subprocess.DEVNULL,
+            )
+        except FileNotFoundError as e:
+            raise RuntimeError(
+                "the `az` CLI was not found on PATH — install the Azure CLI "
+                "(https://learn.microsoft.com/cli/azure/install-azure-cli) before "
+                "opening an azure tunnel"
+            ) from e
+        atexit.register(self._cleanup)
+
+        if not wait_local_open(self.local_port, timeout=30.0):
+            stderr = ""
+            if self._proc and self._proc.poll() is not None:
+                err = self._proc.stderr
+                if err:
+                    stderr = err.read().decode("utf-8", "replace")
+            self._cleanup()
+            raise RuntimeError(
+                f"Azure Bastion tunnel did not come up on 127.0.0.1:{self.local_port} "
+                f"(bastion={self.conn.bastion_name}, target={self.conn.target_resource_id}). "
+                f"az stderr: {stderr.strip()[:500]}"
+            )
+        return self.local_port
+
+    def __exit__(self, *exc) -> None:
+        self._cleanup()
+
+    def _cleanup(self) -> None:
+        if self._proc is not None:
+            _terminate(self._proc)
+            self._proc = None

{dbctl-0.7.2 → dbctl-0.7.3}/dbctl/tunnels/base.py

@@ -62,7 +62,9 @@ def build_tunnel(conn: Connection, *, override_port: int | None = None) -> Tunne
     it's the right place for that lazy resolution to happen.
     """
     from dbctl.refs import resolve_connection
+    from dbctl.tunnels.azure import AzureBastionTunnel as _Azure
     from dbctl.tunnels.direct import DirectTunnel as _Direct
+    from dbctl.tunnels.gcp import GcpIapTunnel as _Gcp
     from dbctl.tunnels.k8s import K8sTunnel as _K8k
     from dbctl.tunnels.ssh import SshTunnel as _Ssh
     from dbctl.tunnels.ssm import SsmTunnel as _Ssm
@@ -91,6 +93,16 @@ def build_tunnel(conn: Connection, *, override_port: int | None = None) -> Tunne
             if override_port is not None:
                 conn.direct = conn.direct.model_copy(update={"port": override_port})
             return _Direct(conn.direct)
+        case "azure":
+            assert conn.azure
+            if override_port is not None:
+                conn.azure = conn.azure.model_copy(update={"local_port": override_port})
+            return _Azure(conn.azure)
+        case "gcp":
+            assert conn.gcp
+            if override_port is not None:
+                conn.gcp = conn.gcp.model_copy(update={"local_port": override_port})
+            return _Gcp(conn.gcp)
         case _:  # pragma: no cover - exhaustive
             raise ValueError(f"unknown tunnel type {conn.type!r}")
 

dbctl-0.7.3/dbctl/tunnels/gcp.py

@@ -0,0 +1,76 @@
+"""GCP Identity-Aware Proxy (IAP) TCP tunnel via the ``gcloud`` CLI subprocess."""
+
+from __future__ import annotations
+
+import atexit
+import shutil
+import subprocess
+
+from dbctl.config import GcpIapTunnel as _Conn
+from dbctl.tunnels.base import _terminate, find_free_port, wait_local_open
+
+
+class GcpIapTunnel:
+    def __init__(self, conn: _Conn) -> None:
+        self.conn = conn
+        self.local_host = "127.0.0.1"
+        self.local_port = conn.local_port or find_free_port()
+        self._proc: subprocess.Popen | None = None
+
+    def __enter__(self) -> int:
+        # On Windows the Google Cloud SDK installs as `gcloud.cmd`, not
+        # `gcloud.exe` — subprocess.Popen(["gcloud", ...]) without
+        # shell=True raises FileNotFoundError even though `gcloud` is
+        # genuinely on PATH, because CreateProcess won't resolve a bare
+        # command name to a .cmd/.bat launcher. Resolving the full path
+        # via shutil.which first fixes this on Windows and is a no-op on
+        # Linux/macOS (real executable).
+        cmd = [
+            shutil.which("gcloud") or "gcloud",
+            "compute",
+            "start-iap-tunnel",
+            self.conn.instance,
+            str(self.conn.remote_port),
+            f"--local-host-port=localhost:{self.local_port}",
+            "--zone",
+            self.conn.zone,
+        ]
+        if self.conn.project:
+            cmd.append(f"--project={self.conn.project}")
+
+        try:
+            self._proc = subprocess.Popen(
+                cmd,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+                stdin=subprocess.DEVNULL,
+            )
+        except FileNotFoundError as e:
+            raise RuntimeError(
+                "the `gcloud` CLI was not found on PATH — install the Google Cloud "
+                "CLI (https://cloud.google.com/sdk/docs/install) before opening a "
+                "gcp tunnel"
+            ) from e
+        atexit.register(self._cleanup)
+
+        if not wait_local_open(self.local_port, timeout=30.0):
+            stderr = ""
+            if self._proc and self._proc.poll() is not None:
+                err = self._proc.stderr
+                if err:
+                    stderr = err.read().decode("utf-8", "replace")
+            self._cleanup()
+            raise RuntimeError(
+                f"GCP IAP tunnel did not come up on 127.0.0.1:{self.local_port} "
+                f"(instance={self.conn.instance}, zone={self.conn.zone}). "
+                f"gcloud stderr: {stderr.strip()[:500]}"
+            )
+        return self.local_port
+
+    def __exit__(self, *exc) -> None:
+        self._cleanup()
+
+    def _cleanup(self) -> None:
+        if self._proc is not None:
+            _terminate(self._proc)
+            self._proc = None

{dbctl-0.7.2 → dbctl-0.7.3}/docs/connections.md

@@ -38,7 +38,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. |
+| `type`          | `ssm` \| `ssh` \| `k8s` \| `direct` \| `azure` \| `gcp` | **yes**  | selects the tunnel implementation. |
 | `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. |
@@ -50,6 +50,8 @@ overlap with a clear message.
 | `ssh`           | [`SshTunnel`](#ssh-block)                 | yes if `type: ssh` | tunnel params. |
 | `k8s`           | [`K8sTunnel`](#k8s-block)                 | yes if `type: k8s` | tunnel params. |
 | `direct`        | [`DirectTunnel`](#direct-block)           | yes if `type: direct` | upstream params (no tunnel). |
+| `azure`         | [`AzureBastionTunnel`](#azure-block)      | yes if `type: azure` | tunnel params. |
+| `gcp`           | [`GcpIapTunnel`](#gcp-block)              | yes if `type: gcp` | tunnel params. |
 | `healthcheck`   | [`Healthcheck`](#healthcheck-block)      | no       | `SELECT 1` by default. |
 | `info`          | list of [`InfoQuery`](#info-query)        | no       | named introspection queries that `dbctl <conn> info <name>` can run. |
 | `safety`        | [`Safety`](#safety-block)                 | no       | gates DML. |
@@ -256,6 +258,54 @@ the database without a bastion.
 > driver, install `ODBC Driver 18 for SQL Server` (or similar) on your
 > system first.
 
+## `azure` block
+
+Azure Bastion tunnel to a VM via `az network bastion tunnel`. The `az` CLI
+on your `PATH` is invoked as a subprocess; your existing `az login` session
+is used directly. Requires an Azure Bastion resource on the **Standard**
+SKU (the Basic SKU doesn't support the native-client tunnel command) in the
+target VM's VNet.
+
+```yaml
+azure:
+  resource_group: prod-rg
+  bastion_name: prod-bastion
+  target_resource_id: /subscriptions/xxxx/resourceGroups/prod-rg/providers/Microsoft.Compute/virtualMachines/prod-db-vm
+  subscription: prod                          # optional; az CLI --subscription (name or id)
+  remote_port: 5432                           # port on the target VM to forward
+  local_port: 0                               # 0 = dbctl picks a free local port
+```
+
+- `target_resource_id` is the full ARM resource id of the target VM (the
+  bastion's target, not the bastion itself).
+- `local_port: 0` makes `dbctl` discover a free port itself before invoking
+  `az`, the same as the `ssm` / `ssh` / `k8s` tunnels.
+- The subprocess is terminated cleanly on exit; an `atexit` fallback covers
+  hard crashes.
+
+## `gcp` block
+
+GCP Identity-Aware Proxy (IAP) TCP tunnel to a Compute Engine instance via
+`gcloud compute start-iap-tunnel`. The `gcloud` CLI on your `PATH` is
+invoked as a subprocess; your existing `gcloud auth login` session is used
+directly. Requires IAP TCP forwarding enabled for the target instance's
+network and the caller to hold the `roles/iap.tunnelResourceAccessor` IAM
+role (directly or via a broader role).
+
+```yaml
+gcp:
+  project: my-gcp-project                     # optional; blank = gcloud's active project
+  zone: europe-west1-b
+  instance: prod-db-vm
+  remote_port: 5432                           # port on the instance to forward
+  local_port: 0                               # 0 = dbctl picks a free local port
+```
+
+- `local_port: 0` makes `dbctl` discover a free port itself before invoking
+  `gcloud`, the same as the other tunnel types.
+- The subprocess is terminated cleanly on exit; an `atexit` fallback covers
+  hard crashes.
+
 ## `healthcheck` block
 
 ```yaml
@@ -479,6 +529,57 @@ connections:
       allowed_operations: []
 ```
 
+### Azure Postgres VM via Azure Bastion
+
+```yaml
+connections:
+  azure-prod-pg:
+    description: "Production Postgres VM reached via Azure Bastion"
+    aliases: [prod]
+    type: azure
+    driver: postgresql+psycopg
+    database: app
+    username: app_admin
+    password_env: DBCTL_AZURE_PROD_PG_PASSWORD
+    azure:
+      resource_group: prod-rg
+      bastion_name: prod-bastion
+      target_resource_id: /subscriptions/xxxx/resourceGroups/prod-rg/providers/Microsoft.Compute/virtualMachines/prod-db-vm
+      subscription: prod
+      remote_port: 5432
+      local_port: 0
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: false
+      allowed_operations: []
+```
+
+### GCP Cloud SQL-adjacent VM via IAP tunnel
+
+```yaml
+connections:
+  gcp-prod-pg:
+    description: "Production Postgres VM reached via GCP IAP tunnel"
+    aliases: [prod]
+    type: gcp
+    driver: postgresql+psycopg
+    database: app
+    username: app_admin
+    password_env: DBCTL_GCP_PROD_PG_PASSWORD
+    gcp:
+      project: my-gcp-project
+      zone: europe-west1-b
+      instance: prod-db-vm
+      remote_port: 5432
+      local_port: 0
+    healthcheck: { query: "SELECT 1" }
+    safety:
+      confirm: true
+      read_only: false
+      allowed_operations: []
+```
+
 ### SQL Server with Windows SSO (Integrated Security)
 
 ```yaml

{dbctl-0.7.2 → dbctl-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dbctl"
-version = "0.7.2"
+version = "0.7.3"
 description = "Generic CLI to monitor, control, and administer multiple databases via SSM, SSH, or direct connection."
 readme = "README.md"
 requires-python = ">=3.12"