Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
17cef62
feat: add AWS SSM database tunnels via CLI
enkhjile Nov 14, 2026
cb71fb3
fix: align tunnel controls and clarify form help
enkhjile Nov 14, 2026
677872d
refactor: name SSM connection attempt states
enkhjile Nov 14, 2026
888892e
refactor: share SSM child output capture
enkhjile Nov 14, 2026
ffe2f2e
fix(connections): close the Windows SSM cleanup race
enkhjile Nov 14, 2026
df337b0
fix(connections): animate SSM fields like SSH
enkhjile Nov 14, 2026
f232961
ci: keep the live AWS SSM test opt-in
enkhjile Nov 14, 2026
b990bd5
fix(connections): prevent SSM profiles connecting directly after down…
enkhjile Nov 15, 2026
18512fd
fix(connections): accept SSM identity punctuation and validate restor…
enkhjile Nov 15, 2026
4da71bd
feat(connections): guide SSM dependency setup
enkhjile Nov 15, 2026
d53cc76
fix(connections): refresh SSM setup checks and clean up probes
enkhjile Nov 15, 2026
a9186ce
refactor(ssm): simplify diagnostics and polish advanced control
enkhjile Nov 15, 2026
a6c9b9b
fix(connections): validate SSM tools and stabilize setup UI
enkhjile Nov 15, 2026
6f62812
test(connections): assert SSM listener and descendant cleanup
enkhjile Nov 15, 2026
8634481
fix: restore the button label's one-em line height
ShayanAbbas1 Nov 15, 2026
654de3a
test(connections): give the SSM probe timeout test time to start its …
ShayanAbbas1 Nov 15, 2026
c737810
perf(connections): block the SSM watchdog instead of polling
ShayanAbbas1 Nov 15, 2026
86fa475
test(connections): let the fake SSM plugin outlive a loaded runner's …
ShayanAbbas1 Nov 15, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -159,12 +159,13 @@ jobs:
docker compose up -d --wait
# nextest for the retries .config/nextest.toml gives the live tests. Its
# test() matches any part of a name, as cargo test's filters do. CI has
# no Snowflake account, and the live Snowflake tests panic without one;
# the mock tests cover the same ground offline.
# no Snowflake account or AWS SSM target/credentials; those live tests
# are explicitly opt-in. Their offline tests still run here.
- name: test
run: >-
cargo nextest run --run-ignored all -E 'not (test(snowflake::tests::live_)
| test(turso::tests::live_) | test(reads_run_at_once) | test(conformance)
| test(turso::tests::live_) | test(live_ssm_)
| test(reads_run_at_once) | test(conformance)
| test(external::db2::) | test(external::psqlodbc::))'
# These time two reads run at once against the same two in turn. With
# the rest of the suite sharing the runner's cores, a CPU-bound engine
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,10 @@ statements you type run under the connection's mode. See
Unix socket on the SSH host, optionally as another user (Run as); the server
needs `socat`, and passwordless `sudo` for it when Run as is set. TLS modes
other than `disable` and `prefer` are refused there.
- **Reach private databases through AWS SSM.** Choose AWS SSM in the connection
form to use your installed AWS CLI and Session Manager plugin, with profile
and region settings and automatic local port selection. See
[SSM tunnels](docs/ssm-tunnels.md) for setup and TLS restrictions.
- **Sign in with a short-lived token.** On Postgres, MySQL, MariaDB, SQL
Server, Redis and ClickHouse, a profile's Password command prints the
password at every login, so cloud IAM auth keeps working after the token
Expand Down
8 changes: 8 additions & 0 deletions docs/agents/session.md
Original file line number Diff line number Diff line change
Expand Up @@ -629,6 +629,14 @@ one waiting on a column ignores whatever is typed into it.
dialect it does not know, the dialect's own refusal for one no plugin may
carry, or the string's `storable()` refusal for a hand-edited secret; a
`generic` engine with no plugin gets the Generic refusal.
- **SSM profiles have a downgrade guard.** `StoredProfile` serializes its
engine as a table containing a required `ssm` table and the original engine
inside it. Old readers' `Option<String>` engine cannot decode that table,
even when the unavailable-profile reader falls back to plain deserialization.
Current readers require the tunnel payload before normalizing the engine;
unknown guard shapes remain unavailable. The guard is derived from `ssm`
on every serialization, including held-back profiles, so earlier development
profiles gain protection on save. Direct and SSH profiles keep their format.
- **Passwords** go through `keyring`, never into `profiles.toml`: Keychain on
macOS, Secret Service on Linux, Credential Manager on Windows. So does an
SSH key's passphrase, as an item per profile in a service of its own.
Expand Down
36 changes: 36 additions & 0 deletions docs/agents/ssh-tunnels.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,3 +231,39 @@ It is not a forward.
`ponytail:` the upgrade is a DBDelve-owned master (`-M -S <private path>
-o ControlPersist=no`, watched like a tunnel) the bridges multiplex over;
Windows' OpenSSH cannot multiplex.

## AWS SSM

`db::tunnel::Tunnel` is the closed SSH/SSM dispatch for TCP forwarding; the
Unix socket bridge remains in `ssh`. Every driver keeps calling `dial` before
opening another socket. Both transport selections must reach the same TLS,
MongoDB discovery, and ODBC endpoint safety gates. A profile containing both
is refused, never given precedence silently.

`ssm` invokes the installed CLI with argument vectors and JSON parameters,
using `localPortNumber=0`. The Session Manager plugin prints its assigned port
after binding `localhost`; that stdout line, not a TCP probe or StartSession
banner, is the readiness signal. The AWS CLI waits synchronously for its plugin.
The watchdog reports child exit before its cleanup grace period so an exited
CLI cannot leave a seemingly live tunnel during that wait. Unknown readiness
output times out. Raw output must never reach logs or errors: a CLI traceback
can include the plugin's argv and AWS session token.

A re-exec watchdog runs before GPUI starts. Its stdin belongs to the app;
EOF ends the CLI's process group on Unix, or closes its Windows Job Object.
It clears inherited signal masks on Unix, gives the plugin a brief TERM grace
period, and kills the whole group afterward. SIGPIPE is ignored so reporting
child exit cannot interrupt cleanup. Its libtest constructor runs the same
entry point before the test harness. On Windows the watchdog joins its own
kill-on-close job before spawning the CLI, so the CLI and plugin inherit job
membership from birth. Closing the job ends the watchdog as well as its children;
no spawn-to-assignment window is left in this SSM path.

A `ConnectAttempt` is runtime-only, never serialized. The form's Running test
and profile's Connecting state own cancellation guards; replacing either
cancels the old attempt. Completion atomically disarms cancellation so dropping
the guard cannot close a successful connection. The token travels in SSM's
runtime config to preserve existing driver interfaces. A weak process watcher
also interrupts a database handshake after tunnel readiness if cancelled.
Remote termination is best effort with its own three-second budget; local
teardown never waits for AWS.
4 changes: 2 additions & 2 deletions docs/agents/ui.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,9 +162,9 @@ curves, and hover states are instant. These things move:
clock and curve (`Part::Form`, read off `ConnectionForm::opened`), over the
same contours, which fade in only when the welcome surface was not already
showing them (`ConnectionForm::backdrop_shown`). It stops asking for frames
at `form_entrance_ms`, and `reduce_motion` skips it. Its SSH rows settle in
at `form_entrance_ms`, and `reduce_motion` skips it. Its SSH and AWS SSM rows settle in
once over 220ms when the tunnel is switched on (`revealed`, keyed by the
row, so they replay only on remounting). Neither repeats.
transport and row, so switching transports replays the entrance). Neither repeats.

Anything else that moves needs raising first, and a second repeating animation
means building the shared throttled clock and moving both onto it.
Expand Down
127 changes: 127 additions & 0 deletions docs/ssm-tunnels.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,127 @@
# AWS SSM tunnels

Choose **AWS SSM** under **Tunnel** in the connection form to forward a
private database connection through a Systems Manager managed instance.
DBDelve runs your installed AWS CLI and Session Manager plugin. The database
Host and Port remain the destination as seen from that instance; DBDelve
chooses the local port automatically.

## Before connecting

- Install AWS CLI v2 and the Session Manager plugin on this computer.
- Configure credentials with the AWS CLI. For an SSO profile, run
`aws sso login --profile your-profile` before connecting.
- Use an SSM-managed instance (`i-…` or `mi-…`) with SSM Agent 3.1.1374.0 or
later, online in the selected region and reachable through Session Manager.
- The instance must resolve and reach the database's hostname and port.
- Your identity needs permission to start a session on that instance with
`AWS-StartPortForwardingSessionToRemoteHost`, and to terminate its sessions.
The instance also needs its usual Systems Manager permissions and network
access to the service.

See [AWS's remote-host forwarding requirements](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html#sessions-remote-port-forwarding)
and [plugin installation](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html).

## Connection settings

**Target instance** is required. **AWS profile** and **AWS region** are optional:
blank values let the CLI use its normal credential and region resolution.
Assumed roles, credential processes, environment credentials, and existing SSO
sessions remain the CLI's responsibility. DBDelve does not store AWS keys or
perform an interactive login.

Selecting AWS SSM checks both tools locally in the background. **Found** means
that the executable's `--version` command completed successfully and returned
recognized version output; it does not verify AWS credentials, permissions,
or database connectivity. Each check has a three-second timeout.
**Wrong executable** distinguishes an unrecognized tool from **Missing** or
**Couldn't run**. These states offer **Choose executable…** and an official
**Installation guide**. After installation, use
**Check again**; if your desktop app's PATH has not picked up the installation,
choose the executable under **Advanced** or restart the app.

The optional **AWS CLI path** and **Plugin path** under **Advanced** accept absolute paths, useful
when an app launched from Finder or a desktop launcher has a different PATH
from your shell. The plugin file must be named `session-manager-plugin`
(`session-manager-plugin.exe` on Windows). Paths containing spaces work.
On Windows, a different plugin next to `aws.exe` takes precedence over PATH;
DBDelve refuses that conflict and asks you to select that copy or another CLI.
No shell startup files are loaded. Install the tools separately; DBDelve does
not download them.

**Test** opens the same transport and database handshake as **Connect**, then
closes it. Editing or duplicating a connection preserves its SSM settings.
Choosing another tunnel type keeps the unsaved fields, but saves only the
selected transport. SSH and SSM cannot be combined.

## Encryption and database support

SSM forwards a single TCP destination. Unix sockets, SSH Run as, ECS targets,
custom SSM documents, host lists, and SRV/discovery-based routes are not
supported by this option. File databases do not have a tunnel selector.

The TCP routing paths already used for SSH are used for SSM: PostgreSQL,
MySQL/MariaDB, SQL Server, Redis, ClickHouse, and supported explicit
ODBC endpoints. All their existing tunnel restrictions still apply:

- PostgreSQL, SQL Server and ClickHouse keep the real database hostname for
TLS verification while dialing the local forward.
- MySQL/MariaDB and Redis refuse `verify-full` through a tunnel because their
drivers cannot separate the dial address from the verification name.
- MongoDB SSM is refused: its driver opens background connections without a
hook to recheck tunnel liveness. Its existing SSH support is unchanged.
- ODBC requires an explicit endpoint that DBDelve can safely rewrite. DSNs
and unsupported/ambiguous connection strings are refused. TLS remains the
driver's responsibility; configure its separate certificate hostname where
available, otherwise a hostname mismatch fails.

No TLS mode is silently weakened. Password commands, including RDS IAM token
commands, still receive the original database host and port.

## Failures and cleanup

Missing tools, expired credentials/SSO, access denial, and an offline target
produce an actionable error. Startup has a 30-second limit. Unknown CLI
output fails closed; raw tracebacks are not shown because they can contain
session tokens. A database handshake still has to succeed after the local
listener is ready.

Closing or retesting the form cancels the old attempt. Disconnecting ends the
local CLI/plugin process tree. On Unix a watchdog survives the app and uses
its lifetime pipe to detect even an app crash; on Windows it owns a kill-on-close
Job Object. Local cleanup is independent of a bounded, best-effort remote
`terminate-session` call. Abrupt crashes or lost network access may leave the
remote session visible until AWS expires it. A dropped tunnel never falls
back to a direct database connection or replays a query.

**Downgrading:** SSM profiles are saved with a non-string engine guard
(`[profiles.engine.ssm]`) as well as their tunnel settings. Older releases
cannot read that engine as a direct connection. Releases with unavailable-profile
support retain the whole profile without opening it; earlier releases, or the
plain-reader fallback, reject the file and may preserve it as
`profiles.toml.broken`. Keep a backup or use a separate application variant
when testing older versions, since those versions cannot use the SSM profile.
Existing direct and SSH profiles retain their original format.

SSM profiles from earlier development builds acquire the guard when saved by
this build. An old copy that has never been saved by the fixed build remains
unsafe to open in an older release. A guarded profile with missing tunnel
settings is refused, never restored as a direct connection.

## Opt-in live verification

Normal tests use fake child processes and loopback sockets, without AWS
credentials. A live PostgreSQL integration test is ignored by default:

```sh
export DBDELVE_SSM_POSTGRES_URL='postgresql://user:password@private-db.example/db?sslmode=verify-full'
export DBDELVE_SSM_TARGET='i-0123456789abcdef0'
export DBDELVE_SSM_PROFILE='your-profile'
export DBDELVE_SSM_REGION='your-region'
cargo test live_ssm_query_side_connection_cancel_and_cleanup -- --ignored
```

Optional `DBDELVE_SSM_AWS_CLI` and `DBDELVE_SSM_PLUGIN` select absolute tool
paths. Use a disposable test database and a role permitted to query it. This
checks a query, a secondary connection, cancellation, and listener cleanup;
`verify-full` and a trusted server certificate also exercise TLS identity.
Loading
Loading