From 0a7b88358e9481726fc8a3b064c71eb9a8fe831b Mon Sep 17 00:00:00 2001 From: Andrea Debernardi Date: Sat, 18 Jul 2026 14:10:01 +0200 Subject: [PATCH 1/3] docs(wiki): document SSH forwarding to a Unix socket --- content/wiki/connections.md | 1 + content/wiki/ssh-tunneling.md | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/content/wiki/connections.md b/content/wiki/connections.md index 8a9be0a..6b455d6 100644 --- a/content/wiki/connections.md +++ b/content/wiki/connections.md @@ -52,6 +52,7 @@ When creating a connection (`+` button in the sidebar or `Cmd/Ctrl + Shift + N`) | **Save in keychain** | — | Controls whether the password persists after closing | | **SSH enabled** | No | Activates the SSH tunnel for this connection | | **SSH profile** | — | Which saved SSH profile to use for the tunnel | +| **Socket path** | No | Unix socket on the SSH server the tunnel forwards to instead of Host and Port, for databases that only listen on a socket. Disables database TLS (the SSH tunnel still encrypts the path). See [SSH Tunneling → Forwarding to a Unix Socket](/wiki/ssh-tunneling#forwarding-to-a-unix-socket). | | **Allow interactive prompts** | No | Lets the SSH tunnel prompt in-app for a key passphrase, security-key PIN, or password when it can't authenticate silently. See [SSH Tunneling → Interactive Authentication](/wiki/ssh-tunneling#interactive-authentication-passphrases--security-keys). | | **Startup script** | No | SQL run on every new pooled connection (see [Startup Script](#startup-script) below). | | **Kubernetes** | No | Tunnels the connection through a managed `kubectl port-forward`. Mutually exclusive with SSH. See [Kubernetes Tunneling](/wiki/kubernetes-tunneling). | diff --git a/content/wiki/ssh-tunneling.md b/content/wiki/ssh-tunneling.md index 287db01..db20a34 100644 --- a/content/wiki/ssh-tunneling.md +++ b/content/wiki/ssh-tunneling.md @@ -92,6 +92,18 @@ Click **Test** before saving. Tabularis performs a real SSH handshake and report When you connect, the tunnel is established first, then the database driver connects through it. If the tunnel fails, the exact SSH error is surfaced — no generic "connection refused" messages. +## Forwarding to a Unix Socket + +Some databases only listen on a Unix socket: MySQL with `skip_networking`, PostgreSQL with `listen_addresses = ''`. For those, set the optional **Socket Path** field in the SSH section of the connection editor. + +When a socket path is set: + +- The SSH server connects to that socket instead of Host and Port (both fields grey out). Under the hood this is a `direct-streamlocal@openssh.com` channel on the Russh backend, and `ssh -L :/path/to/socket` on the System SSH backend. +- Database TLS is turned off automatically. A server listening on a Unix socket cannot negotiate TLS, and the SSH tunnel already encrypts the whole path. +- The path must be absolute, as it appears on the SSH server, and must point at the socket file itself — not the directory holding it. Typical values are `/var/run/mysqld/mysqld.sock` (MySQL) and `/var/run/postgresql/.s.PGSQL.5432` (PostgreSQL). + +The socket path belongs to the database connection, not to the SSH profile, so a single bastion profile can serve both TCP and socket-only databases. + ## Multi-Hop / ProxyJump For databases behind multiple bastion layers, define the chain in `~/.ssh/config` and use the System SSH backend (key-only auth, no password): From aa7ffa18e31fce44a176f025f89ee70daec18460 Mon Sep 17 00:00:00 2001 From: Andrea Debernardi Date: Sat, 18 Jul 2026 15:43:19 +0200 Subject: [PATCH 2/3] docs(wiki): document local Unix socket connections Companion to TabularisDB/tabularis#492: the PR now also lets the MySQL and PostgreSQL drivers dial a Unix socket on the local machine directly, gated by the new unix_socket driver capability. Adds the field to the connection-profile table, a Local Unix socket section in connections.md, the capability row in plugins.md, and a cross-link from the SSH forwarding section. --- content/wiki/connections.md | 14 ++++++++++++++ content/wiki/plugins.md | 1 + content/wiki/ssh-tunneling.md | 2 +- 3 files changed, 16 insertions(+), 1 deletion(-) diff --git a/content/wiki/connections.md b/content/wiki/connections.md index 6b455d6..d5ea6a4 100644 --- a/content/wiki/connections.md +++ b/content/wiki/connections.md @@ -46,6 +46,7 @@ When creating a connection (`+` button in the sidebar or `Cmd/Ctrl + Shift + N`) | **Driver** | Yes | Selects the database type | | **Host** | Yes* | Hostname or IP address | | **Port** | Yes* | Auto-filled from the driver default | +| **Local socket path** | No | Unix socket on this machine the drivers connect to instead of Host and Port (MySQL and PostgreSQL). Disables database TLS. Ignored while an SSH or Kubernetes tunnel is enabled. See [Local Unix socket](#local-unix-socket-mysql--postgresql) below. | | **Database** | Yes* | The database name to connect to | | **Username** | Yes* | Database user | | **Password** | No | Stored in OS keychain; never written to disk | @@ -96,6 +97,19 @@ SELECT set_config('app.bypass_rls', 'on', false); applies to every subsequent query instead of randomly depending on which pooled connection you landed on. Any `SET` or session-setup statement works; multiple statements can be separated normally, and blank or whitespace-only scripts are skipped. The script is stored with the connection profile as non-secret configuration. +### Local Unix socket (MySQL / PostgreSQL) + +A database on the same machine can be reached through its Unix socket instead of TCP: set the optional **Local Socket Path** field in the General tab. No tunnel is involved — the drivers dial the socket directly. + +When a local socket path is set: + +- The drivers connect to that socket instead of Host and Port (both fields grey out). +- Point at the socket file itself: typically `/tmp/mysql.sock` (MySQL on macOS/Homebrew), `/var/run/mysqld/mysqld.sock` (MySQL on Linux), or `/var/run/postgresql/.s.PGSQL.5432` (PostgreSQL). For PostgreSQL, a plain socket *directory* also works, paired with the Port field. +- Database TLS is turned off automatically — it cannot be negotiated over a Unix socket, and the traffic never leaves the machine. +- The field is ignored while an SSH or Kubernetes tunnel is enabled: the tunnel owns the route to the database. To reach a *remote* socket-only database, use [SSH Tunneling → Forwarding to a Unix Socket](/wiki/ssh-tunneling#forwarding-to-a-unix-socket) instead. + +Plugin drivers can opt into the field with the `unix_socket` capability in their manifest (see [Plugins → Capabilities](/wiki/plugins#capabilities)). + ### SQLite For SQLite, provide the absolute path to the `.db` or `.sqlite` file using the file picker. There is no host, port, or authentication. diff --git a/content/wiki/plugins.md b/content/wiki/plugins.md index 224b6a1..e37ff6d 100644 --- a/content/wiki/plugins.md +++ b/content/wiki/plugins.md @@ -92,6 +92,7 @@ Every plugin must include a `manifest.json` that tells Tabularis its capabilitie | `connection_string_example` | string | Optional placeholder example shown in the connection string import field (e.g. `"clickhouse://user:pass@localhost:9000/db"`). `connectionStringExample` is also accepted. | | `manage_tables` | bool | `true` to enable table and column management UI (Create Table, Add/Modify/Drop Column, Drop Table). Does not control index or FK operations. Defaults to `true`. | | `readonly` | bool | When `true`, the driver is read-only: all data modification operations (INSERT, UPDATE, DELETE) are disabled in the UI. Table and column management is also hidden regardless of `manage_tables`. Defaults to `false`. | +| `unix_socket` | bool | `true` if the driver can connect through a local Unix socket instead of host:port. Shows the **Local Socket Path** field in the connection editor; the path reaches the plugin in the connection params as `unix_socket_path`. `unixSocket` is also accepted. Defaults to `false`. | ### Data Type Categories diff --git a/content/wiki/ssh-tunneling.md b/content/wiki/ssh-tunneling.md index db20a34..17f0175 100644 --- a/content/wiki/ssh-tunneling.md +++ b/content/wiki/ssh-tunneling.md @@ -94,7 +94,7 @@ When you connect, the tunnel is established first, then the database driver conn ## Forwarding to a Unix Socket -Some databases only listen on a Unix socket: MySQL with `skip_networking`, PostgreSQL with `listen_addresses = ''`. For those, set the optional **Socket Path** field in the SSH section of the connection editor. +Some databases only listen on a Unix socket: MySQL with `skip_networking`, PostgreSQL with `listen_addresses = ''`. For those, set the optional **Socket Path** field in the SSH section of the connection editor. (For a socket-only database on *your own* machine, no tunnel is needed — use the **Local Socket Path** field instead; see [Connections → Local Unix socket](/wiki/connections#local-unix-socket-mysql--postgresql).) When a socket path is set: From 200b090c634355e82d05ad7b12172f1fa6a459a5 Mon Sep 17 00:00:00 2001 From: Andrea Debernardi Date: Sat, 18 Jul 2026 15:59:38 +0200 Subject: [PATCH 3/3] docs(wiki): unify the socket docs around the single Socket Path field The app now has one unix_socket_path field with tunnel-relative semantics (like Host and Port): dialed locally without a tunnel, by the SSH server with SSH enabled, ignored with Kubernetes. Merge the two connection-table rows into one, rewrite the connections.md section as 'Connecting over a Unix socket', point the SSH forwarding section at the shared field, and update the unix_socket capability row. --- content/wiki/connections.md | 18 ++++++++---------- content/wiki/plugins.md | 2 +- content/wiki/ssh-tunneling.md | 2 +- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/content/wiki/connections.md b/content/wiki/connections.md index d5ea6a4..f20b2ee 100644 --- a/content/wiki/connections.md +++ b/content/wiki/connections.md @@ -46,14 +46,13 @@ When creating a connection (`+` button in the sidebar or `Cmd/Ctrl + Shift + N`) | **Driver** | Yes | Selects the database type | | **Host** | Yes* | Hostname or IP address | | **Port** | Yes* | Auto-filled from the driver default | -| **Local socket path** | No | Unix socket on this machine the drivers connect to instead of Host and Port (MySQL and PostgreSQL). Disables database TLS. Ignored while an SSH or Kubernetes tunnel is enabled. See [Local Unix socket](#local-unix-socket-mysql--postgresql) below. | +| **Socket path** | No | Unix socket the database listens on at the connection's destination, replacing Host and Port. Dialed directly on this machine without a tunnel (MySQL/PostgreSQL); with SSH, the SSH server connects to it. Disables database TLS. Ignored with Kubernetes. See [Connecting over a Unix socket](#connecting-over-a-unix-socket) below. | | **Database** | Yes* | The database name to connect to | | **Username** | Yes* | Database user | | **Password** | No | Stored in OS keychain; never written to disk | | **Save in keychain** | — | Controls whether the password persists after closing | | **SSH enabled** | No | Activates the SSH tunnel for this connection | | **SSH profile** | — | Which saved SSH profile to use for the tunnel | -| **Socket path** | No | Unix socket on the SSH server the tunnel forwards to instead of Host and Port, for databases that only listen on a socket. Disables database TLS (the SSH tunnel still encrypts the path). See [SSH Tunneling → Forwarding to a Unix Socket](/wiki/ssh-tunneling#forwarding-to-a-unix-socket). | | **Allow interactive prompts** | No | Lets the SSH tunnel prompt in-app for a key passphrase, security-key PIN, or password when it can't authenticate silently. See [SSH Tunneling → Interactive Authentication](/wiki/ssh-tunneling#interactive-authentication-passphrases--security-keys). | | **Startup script** | No | SQL run on every new pooled connection (see [Startup Script](#startup-script) below). | | **Kubernetes** | No | Tunnels the connection through a managed `kubectl port-forward`. Mutually exclusive with SSH. See [Kubernetes Tunneling](/wiki/kubernetes-tunneling). | @@ -97,18 +96,17 @@ SELECT set_config('app.bypass_rls', 'on', false); applies to every subsequent query instead of randomly depending on which pooled connection you landed on. Any `SET` or session-setup statement works; multiple statements can be separated normally, and blank or whitespace-only scripts are skipped. The script is stored with the connection profile as non-secret configuration. -### Local Unix socket (MySQL / PostgreSQL) +### Connecting over a Unix socket -A database on the same machine can be reached through its Unix socket instead of TCP: set the optional **Local Socket Path** field in the General tab. No tunnel is involved — the drivers dial the socket directly. +The optional **Socket Path** field in the General tab names the Unix socket the database listens on, replacing Host and Port. Like Host and Port, it is interpreted from the perspective of whoever dials the destination: -When a local socket path is set: +- **No tunnel** — the drivers connect to the socket on this machine directly (MySQL and PostgreSQL). Typical values: `/tmp/mysql.sock` (MySQL on macOS/Homebrew), `/var/run/mysqld/mysqld.sock` (MySQL on Linux), `/var/run/postgresql/.s.PGSQL.5432` (PostgreSQL). For PostgreSQL, a plain socket *directory* also works, paired with the Port field. +- **SSH tunnel** — the SSH server connects to the socket, so the path is as it appears on that server. See [SSH Tunneling → Forwarding to a Unix Socket](/wiki/ssh-tunneling#forwarding-to-a-unix-socket). +- **Kubernetes tunnel** — the field is ignored (`kubectl port-forward` is TCP-only). -- The drivers connect to that socket instead of Host and Port (both fields grey out). -- Point at the socket file itself: typically `/tmp/mysql.sock` (MySQL on macOS/Homebrew), `/var/run/mysqld/mysqld.sock` (MySQL on Linux), or `/var/run/postgresql/.s.PGSQL.5432` (PostgreSQL). For PostgreSQL, a plain socket *directory* also works, paired with the Port field. -- Database TLS is turned off automatically — it cannot be negotiated over a Unix socket, and the traffic never leaves the machine. -- The field is ignored while an SSH or Kubernetes tunnel is enabled: the tunnel owns the route to the database. To reach a *remote* socket-only database, use [SSH Tunneling → Forwarding to a Unix Socket](/wiki/ssh-tunneling#forwarding-to-a-unix-socket) instead. +While a socket path is in effect, Host and Port grey out, and database TLS is turned off automatically — it cannot be negotiated over a Unix socket, and the traffic is either local or already encrypted by the SSH tunnel. -Plugin drivers can opt into the field with the `unix_socket` capability in their manifest (see [Plugins → Capabilities](/wiki/plugins#capabilities)). +Without a tunnel the field appears for drivers that support local socket dialing (built-in MySQL and PostgreSQL; plugins opt in with the `unix_socket` capability, see [Plugins → Capabilities](/wiki/plugins#capabilities)). With SSH enabled it is available for any network driver, since the drivers still connect over TCP to the tunnel's local port. ### SQLite diff --git a/content/wiki/plugins.md b/content/wiki/plugins.md index e37ff6d..4486517 100644 --- a/content/wiki/plugins.md +++ b/content/wiki/plugins.md @@ -92,7 +92,7 @@ Every plugin must include a `manifest.json` that tells Tabularis its capabilitie | `connection_string_example` | string | Optional placeholder example shown in the connection string import field (e.g. `"clickhouse://user:pass@localhost:9000/db"`). `connectionStringExample` is also accepted. | | `manage_tables` | bool | `true` to enable table and column management UI (Create Table, Add/Modify/Drop Column, Drop Table). Does not control index or FK operations. Defaults to `true`. | | `readonly` | bool | When `true`, the driver is read-only: all data modification operations (INSERT, UPDATE, DELETE) are disabled in the UI. Table and column management is also hidden regardless of `manage_tables`. Defaults to `false`. | -| `unix_socket` | bool | `true` if the driver can connect through a local Unix socket instead of host:port. Shows the **Local Socket Path** field in the connection editor; the path reaches the plugin in the connection params as `unix_socket_path`. `unixSocket` is also accepted. Defaults to `false`. | +| `unix_socket` | bool | `true` if the driver can dial a local Unix socket instead of host:port. Shows the **Socket Path** field in the connection editor even without an SSH tunnel (with SSH enabled the field appears for every network driver, since the tunnel does the socket dialing); the path reaches the plugin in the connection params as `unix_socket_path`. `unixSocket` is also accepted. Defaults to `false`. | ### Data Type Categories diff --git a/content/wiki/ssh-tunneling.md b/content/wiki/ssh-tunneling.md index 17f0175..e34d955 100644 --- a/content/wiki/ssh-tunneling.md +++ b/content/wiki/ssh-tunneling.md @@ -94,7 +94,7 @@ When you connect, the tunnel is established first, then the database driver conn ## Forwarding to a Unix Socket -Some databases only listen on a Unix socket: MySQL with `skip_networking`, PostgreSQL with `listen_addresses = ''`. For those, set the optional **Socket Path** field in the SSH section of the connection editor. (For a socket-only database on *your own* machine, no tunnel is needed — use the **Local Socket Path** field instead; see [Connections → Local Unix socket](/wiki/connections#local-unix-socket-mysql--postgresql).) +Some databases only listen on a Unix socket: MySQL with `skip_networking`, PostgreSQL with `listen_addresses = ''`. For those, set the connection's optional **Socket Path** field (General tab). Like Host and Port, the field names the destination from the perspective of whoever dials it: with the SSH tunnel enabled that is the SSH server, so the path is as it appears there. (For a socket-only database on *your own* machine, no tunnel is needed — the same field dials the socket locally; see [Connections → Connecting over a Unix socket](/wiki/connections#connecting-over-a-unix-socket).) When a socket path is set: