From 22290d48412c446ee5f5799ada0989b0b5c3b8b3 Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Sun, 1 Nov 2026 15:00:58 +0700 Subject: [PATCH] docs(connections): document the 0.83.1 connection and SSH changes --- connections/connection-form.mdx | 2 +- connections/credential-profiles.mdx | 4 ++-- connections/ssh-tunneling.mdx | 10 ++++++++++ connections/ssl.mdx | 2 +- connections/urls.mdx | 5 ++++- databases/mongodb.mdx | 9 ++++++--- databases/postgresql.mdx | 2 +- developers/connection-import.mdx | 17 +++++++++++++---- features/connection-sharing.mdx | 21 +++++++++++++++++---- 9 files changed, 55 insertions(+), 17 deletions(-) diff --git a/connections/connection-form.mdx b/connections/connection-form.mdx index 686c1c43..fe78758a 100644 --- a/connections/connection-form.mdx +++ b/connections/connection-form.mdx @@ -33,7 +33,7 @@ The bar along the bottom carries **Test Connection**, **Cancel** and **Save**, p | **Username** | Not pre-filled. Empty means the driver's own default | | **Password** | Stored in the macOS Keychain. **Show password** reveals a saved one after Touch ID or your Mac's password. A connection whose password comes from a [password source](/features/connection-sharing#password-sources) shows the source here, with **Test Source** | | **Prompt for password** | Stores nothing, asks on every connect. Reads **Prompt for API token** on API-only drivers | -| **Use Password File** | PostgreSQL, Redshift, and CockroachDB. Reads `~/.pgpass`, and reports underneath whether the file exists, has `chmod 0600`, and holds a matching line | +| **Use ~/.pgpass** | PostgreSQL, Redshift, CockroachDB, and KingbaseES. Reads `~/.pgpass`, and reports underneath whether the file exists, has `chmod 0600`, and holds a matching line | SQLite, DuckDB, libSQL, and Beancount replace the host fields with a file path. **Browse…** picks a file that exists. **New…** names one that does not, and the file is made when you connect; Beancount opens only an existing ledger, so it has no **New…**. diff --git a/connections/credential-profiles.mdx b/connections/credential-profiles.mdx index 83f0481c..f891dd6b 100644 --- a/connections/credential-profiles.mdx +++ b/connections/credential-profiles.mdx @@ -44,7 +44,7 @@ A linked connection keeps no password of its own. Linking deletes the one it had |---|---| | Saved in the Keychain | Read from the Keychain, under the profile's own id | | Ask every time | Asked for once per profile each time TablePro runs, however many connections use it | -| `~/.pgpass` | Looked up by the host, port, database and username of whichever connection is opening | +| `~/.pgpass` | Looked up by the host, port, database and username of the connection that is opening, when its form has **Use ~/.pgpass**. Any other connection asks for the password | | Read from elsewhere | Resolved from a file, an environment variable, a command's output, 1Password, Vault, AWS Secrets Manager, or a Vault database role | Pick **Saved in the Keychain** unless something else already owns the password. **Read from elsewhere** never leaves this Mac and never syncs. @@ -92,7 +92,7 @@ Right-click a row in **Settings > Profiles** for **Edit…** and **Duplicate**. ## Sharing and sync -An exported connection carries its profile by name, alongside the name, the username and where the password comes from. Importing on a Mac that has no profile of that name creates one set to ask for the password; a profile already there is left as it is and the connection links to it. The password never travels, and a profile reading its password from a file or a command exports as one that asks. +An exported connection carries its profile by name, alongside the name, the username and where the password comes from. Importing on a Mac that has no profile of that name creates one set to **Ask every time**, whatever source the file names, `~/.pgpass` included. To read your own `~/.pgpass`, switch its source in **Settings > Profiles**. A profile already there is left as it is and the connection links to it. The password never travels, and a profile reading its password from a file or a command exports as one that asks. With [iCloud Sync](/features/icloud-sync) on, **Settings > Sync > Credential Profiles** carries profiles between your Macs: the name, the username, and where the password comes from. The password and any additional secrets stay in the Keychain. They cross only while **Passwords** is on in the same pane, and only when saved after it was turned on. A profile set to **Read from elsewhere** arrives as **Ask every time**, and a source set on the second Mac stays on that Mac. diff --git a/connections/ssh-tunneling.mdx b/connections/ssh-tunneling.mdx index 65224672..440a6fb6 100644 --- a/connections/ssh-tunneling.mdx +++ b/connections/ssh-tunneling.mdx @@ -71,6 +71,8 @@ Pick an alias from the **Config Host** picker and `HostName`, `User`, `Port`, `I `Match` blocks take the criteria ssh does, `localnetwork` and `tagged` included. A tunnel counts as `sessiontype none` with an empty `command`, and a criterion TablePro does not know keeps its block from applying. +`CanonicalizeHostname` completes a short name with each `CanonicalDomains` suffix in turn, skipping a name with more dots than `CanonicalizeMaxDots`, and applies to a host reached through a jump only when set to `always`. The completed name is the one dialed and the one its host key is stored under. A DNS alias (CNAME) replaces it only where a `CanonicalizePermittedCNAMEs` rule covers both names. With `CanonicalizeFallbackLocal no`, a name no suffix resolves stops the connection instead of being dialed as typed. + `IdentityFile` picks which agent key is offered, not only which key file is read, and a `.pub` is enough. That is how a 1Password or Secretive key gets pinned to a host. `IdentitiesOnly yes` then drops every agent key the config did not name, which is what keeps a thirty-key agent inside a server's `MaxAuthTries`. Once a connection opens, the hosts, ports and usernames it reached through the config sync to [iPhone and iPad](/ios#route-from-mac), so it opens there too. The config file, keys and key paths stay on the Mac. @@ -200,6 +202,14 @@ An RSA host key keeps working once the server signs with `rsa-sha2-512` or `rsa- The key is RSA, and the server accepts RSA keys only with `ssh-rsa` signatures, which use SHA-1. TablePro signs RSA keys with `rsa-sha2-256` or `rsa-sha2-512`. Add those to `PubkeyAcceptedAlgorithms` in `sshd_config` (`PubkeyAcceptedKeyTypes` before OpenSSH 8.5), or sign in with an Ed25519 or ECDSA key. A server older than OpenSSH 7.2 cannot check either signature, so it needs a key of another type. +### "The SSH host … contains characters ssh does not allow in a host name." / "The SSH user … contains characters ssh does not allow in a user name." + +The name in the message holds a character `ssh` refuses, such as a quote, a backtick, one of `;&|<>(){}`, or a leading `-`. A host also refuses whitespace, `$`, `,` and a backslash. Find the name in **SSH Host**, **SSH User**, a jump host, or a `HostName` line in `~/.ssh/config`, and correct it. + +### "… was not found in any of the CanonicalDomains in ~/.ssh/config, and CanonicalizeFallbackLocal is set to no." + +None of the `CanonicalDomains` suffixes turned the host into a name DNS resolves, and the config forbids dialing the short name. Check that the full name resolves for the domain you expect: `dscacheutil -q host -a name db.example.com`. Add the missing domain to `CanonicalDomains`, or set `CanonicalizeFallbackLocal yes` for that host. + ### "Jump host … failed: …" The step after the colon failed on that jump host, not on the SSH server. Check that hop's **Host**, **Port**, **Username** and **Key File** under **Jump Hosts**, or its `Host` block in `~/.ssh/config`. "Could not open a channel" there means the jump host's `sshd_config` sets `AllowTcpForwarding no`, or it cannot reach the next host. diff --git a/connections/ssl.mdx b/connections/ssl.mdx index 35de11a8..1eb790a6 100644 --- a/connections/ssl.mdx +++ b/connections/ssl.mdx @@ -29,7 +29,7 @@ The certificate rows appear only once **SSL Mode** is anything but Disabled. Eac | **Certificate**, under **CA Certificate** | Verify CA and Verify Identity only | The PEM or DER certificate the server's certificate chains to, for example `/path/to/ca-cert.pem`. Saving without it is blocked, except under Verify Identity on ClickHouse, Kafka, Presto, SAP HANA and Trino, which check the system trust store when it is empty | | **Client Certificate** | Any mode but Disabled | Your certificate, for a server that enforces mutual TLS. Optional otherwise | | **Client Key** | Any mode but Disabled | The matching private key. Required once a client certificate is set | -| **Key Passphrase** | Once **Client Key** has a path, on drivers that support it (Cassandra and ScyllaDB) | The passphrase of an encrypted key. Stored in the Keychain | +| **Key Passphrase** | Once **Client Key** has a path, on drivers that support it (Cassandra, ScyllaDB and MongoDB) | The passphrase of an encrypted key. Stored in the Keychain | SQL Server shows no certificate fields at all and verifies against the system trust store. See [SQL Server](/databases/mssql#limitations). Under Verify Identity, SAP HANA and Kafka verify against the system trust store when **Certificate** is left empty. See [SAP HANA](/databases/sap-hana#ssl%2Ftls). diff --git a/connections/urls.mdx b/connections/urls.mdx index 2a6d4e55..5e8a7397 100644 --- a/connections/urls.mdx +++ b/connections/urls.mdx @@ -106,7 +106,7 @@ An omitted `db_host` defaults to `127.0.0.1`. ## Query parameters -Names are matched case-insensitively. Anything unrecognized is ignored, except on a MongoDB URL, where every unknown parameter is passed to the driver unchanged. +Names are matched case-insensitively. Anything unrecognized is ignored, except on a MongoDB URL, where an unknown parameter is passed to the driver unchanged unless it holds a secret. See [MongoDB](#mongodb). ### Connection @@ -226,6 +226,9 @@ mongodb://user:pass@host1:27017,host2:27017,host3:27017/mydb?replicaSet=rs0 ``` - `uuidRepresentation` sets **Legacy UUID Encoding**. +- `tlsCertificateKeyFile` sets **Client Certificate** and **Client Key** to that file. +- `tlsCertificateKeyFilePassword` sets **Key Passphrase**, and an `AWS_SESSION_TOKEN` inside `authMechanismProperties` sets **AWS Session Token**. Both go to the Keychain, and the rest of `authMechanismProperties` stays an option. +- `proxyPassword` is dropped. - **Copy Connection String** writes an SRV connection as `mongodb+srv://` with no port, and every option percent-encoded. ## What the path component means diff --git a/databases/mongodb.mdx b/databases/mongodb.mdx index 20f68bc6..c6f0ec70 100644 --- a/databases/mongodb.mdx +++ b/databases/mongodb.mdx @@ -30,11 +30,14 @@ The query tab is a JavaScript shell. Write `db.orders.find({status: "new"})` the | **Database** | - | Opens straight into that database. Leave it empty to browse them all | | **Auth Database** | - | Options tab. Where your user account lives, usually `admin` | | **Auth Mechanism** | Default | SCRAM-SHA-1, SCRAM-SHA-256, X.509, or AWS IAM, under Authentication | +| **AWS Session Token** | - | Under Authentication, once **Auth Mechanism** is AWS IAM. Kept in the Keychain | Naming a **Database** skips listing every database on the server, which is worth doing on a cluster with hundreds. Leave it empty and the first non-system database opens instead. `Cmd+K` switches either way, on the same connection, with no reconnect. **Auth Database** is a separate question: it says where your account is defined, not what you browse. Left empty, it follows the **Database** field, except under X.509 and AWS IAM, which authenticate against `$external`. An account defined in `admin` needs **Auth Database** set to `admin` whenever **Database** names something else, or authentication fails. SRV connections authenticate against `admin` regardless, unless told otherwise. Switching databases in the app never changes it, so browsing a database your user has no account in is fine. +AWS IAM takes the access key ID in **Username** and the secret access key in **Password**. Temporary credentials also need their session token in **AWS Session Token**. + Also on the Options tab: **Read Preference**, **Write Concern**, **Use SRV Record**, **Replica Set** name, and **Legacy UUID Encoding**. The server has to be MongoDB 4.0 or later; the driver refuses to connect to anything older. **Write Concern** covers every insert, update and delete, from a query tab or from a save in the data grid, unless the statement passes its own `writeConcern`. Index, collection and database commands, and `db.runCommand`, go to the server as written. On a server that is not a replica set, pick **Default**, **Majority** or **1**: with **2** or **3** every write fails with `cannot use 'w' > 1 when a host is not replicated`. `journal` and `wtimeoutMS` in a pasted connection URL go out with every write too. @@ -55,6 +58,8 @@ mongodb+srv://user:password@cluster.mongodb.net/database `mongodb+srv://` resolves hosts through DNS SRV records and takes no port; one pasted into the field is stripped before connecting. Plain `mongodb://` keeps whatever port you give it. See [Connection URL Reference](/connections/urls). +Secrets in a pasted string do not stay among its options. `tlsCertificateKeyFilePassword` lands in **Key Passphrase** and an `AWS_SESSION_TOKEN` in `authMechanismProperties` lands in **AWS Session Token**, both in the Keychain, and `proxyPassword` is dropped. [MongoDB parameters](/connections/urls#mongodb) lists the ones that fill a field. + ## MongoDB Atlas (SRV) An Atlas connection needs the cluster hostname, a username, and a password. Atlas requires SRV and TLS, so a host ending in `.mongodb.net` gets both turned on for you, TLS only if the SSL mode was still Disabled. Elsewhere the **Use SRV Record** toggle in Advanced does the same job. Add your current IP to the cluster's access list in the Atlas console first: traffic from an address that is not on it times out rather than failing. @@ -69,11 +74,9 @@ The **Hosts** field takes comma-separated pairs (`host1:27017,host2:27017,host3: mongodb://user:pass@host1:27017,host2:27017,host3:27017/db?replicaSet=rs0 ``` - Over an SSH tunnel only the first host is used and the rest of the list is dropped. Replica set discovery and failover are off for that session, with nothing on screen to say so. - ## Browsing collections @@ -375,7 +378,7 @@ valid at the cursor; see [Autocomplete](/features/autocomplete#mongodb). For a q New connections default to **Disabled**, and the driver has no TLS fallback: **Preferred** behaves exactly as **Required**, which is what the Network tab warns about. For an unencrypted local instance use **Disabled** or [SSH tunneling](/connections/ssh-tunneling). See [SSL/TLS](/connections/ssl). -The driver reads a client certificate and its private key from one file. A key chosen in its own file is joined with the certificate in a temporary file only your user can read, removed when the connection closes. +The driver reads a client certificate and its private key from one file. A key chosen in its own file is joined with the certificate in a temporary file only your user can read, removed when the connection closes. An encrypted key takes its passphrase in **Key Passphrase**, which appears once **Client Key** has a path. ## On iPhone and iPad diff --git a/databases/postgresql.mdx b/databases/postgresql.mdx index 8907c044..f1167dbc 100644 --- a/databases/postgresql.mdx +++ b/databases/postgresql.mdx @@ -85,7 +85,7 @@ Connect by hostname, never an IP address: the ticket is for the service principa ### Password file -Turn on **Use Password File** to read the password from `~/.pgpass` instead of typing one. Entries are `hostname:port:database:username:password`, `*` matches any field, first match wins. An empty **Username** matches your macOS login name, and a socket connection matches as described in [Unix socket](#unix-socket). The form reports what it found, including `~/.pgpass has incorrect permissions (needs chmod 0600)`, the one that silently blocks a connect. +Turn on **Use ~/.pgpass** to read the password from `~/.pgpass` instead of typing one. Entries are `hostname:port:database:username:password`, `*` matches any field, first match wins. An empty **Username** matches your macOS login name, and a socket connection matches as described in [Unix socket](#unix-socket). The form reports what it found, including `~/.pgpass has incorrect permissions (needs chmod 0600)`, the one that silently blocks a connect. ## Databases and schemas diff --git a/developers/connection-import.mdx b/developers/connection-import.mdx index edbc4cd3..707be830 100644 --- a/developers/connection-import.mdx +++ b/developers/connection-import.mdx @@ -80,10 +80,19 @@ An `af_` prefix passes a driver-specific field straight to the plugin: `af_repli `replicaSet` on a [MongoDB](/databases/mongodb) connection. Field names come from the plugin, so the engine's own page is where they are listed. -Six field names are dropped on import, along with any name starting with `aws`, because each decides -where a credential comes from: `af_preConnectScript`, `af_preTunnelHost`, `af_preTunnelPort`, -`af_promptForPassword`, `af_sslClientKeyPassphrase` and `af_usePgpass`. The same rule covers -`.tablepro` files, described in +These are dropped on import, because each decides where a credential comes from or runs code on +the Mac. The part after `af_` matches without case. + +- Any name starting with `af_aws` or `af_entra`. +- `af_beancountRunLedgerPlugins`, `af_postDisconnectScript`, `af_preConnectScript`, + `af_preTunnelHost`, `af_preTunnelPort`, `af_promptForPassword`, `af_snowflakeConnectionName`, + `af_spEndpoint`, `af_sslClientKeyPassphrase` and `af_usePgpass`. +- `af_mongoAuthMechanism=MONGODB-AWS`. +- MongoDB secrets: `af_mongoAWSSessionToken`, `af_mongoParam_tlsCertificateKeyFilePassword`, + `af_mongoParam_sslClientCertificateKeyPassword`, `af_mongoParam_proxyPassword`, and + `af_mongoParam_authMechanismProperties` when it carries an `AWS_SESSION_TOKEN`. + +The same rule covers `.tablepro` files, described in [Connection Sharing](/features/connection-sharing#import). Add any of these by hand in the connection editor afterwards. diff --git a/features/connection-sharing.mdx b/features/connection-sharing.mdx index 956da8dc..9a665526 100644 --- a/features/connection-sharing.mdx +++ b/features/connection-sharing.mdx @@ -18,7 +18,7 @@ Passwords stay in your Keychain, so every route here hands over a connection def Right-click a connection > **Share > Export to File…**, selecting several first to export them together, or **File > Export > Export Connections…** for all of them. -The file carries what the connection form holds, from host and port through SSH and SSL configuration, color, icon, tags, the full group path, Safe Mode level, startup commands, AI policy, the Local only flag, and any driver field the plugin does not mark secret. Passwords, key passphrases, TOTP secrets, and secret driver fields stay behind. +The file carries what the connection form holds, from host and port through SSH and SSL configuration, color, icon, tags, the full group path, Safe Mode level, startup commands, AI policy, the Local only flag, and any driver field the plugin does not mark secret. Passwords, key passphrases, TOTP secrets, and secret driver fields stay behind, and so do the settings [Import](#import) strips. Export connections @@ -83,7 +83,20 @@ Group and folder paths match by name from the top down: an existing group or fol Import preview -Anything that decides where a credential comes from is stripped on the way in, from a file and from a link alike: AWS options including IAM authentication, the region, the profile and the RDS endpoint; **Use Password File**; **Prompt for password**; the SSL client key passphrase; the pre-tunnel host and port; and the **Pre-Connect Script** and **Post-Disconnect Script**. Startup SQL and tunnel commands run on every connect, so a file brings them only if you agree: importing lists each one and asks, and **Import Without Commands** is the default. A link's sheet shows its startup SQL in full before you add it. +Anything that decides where a credential comes from, or runs code on your Mac, is stripped on the way in, from a file and from a link alike: + +- AWS options including IAM authentication, the region, the profile and the RDS endpoint +- MongoDB's **AWS IAM** auth mechanism, which imports as **Default**, and the secrets a pasted MongoDB connection string carried +- **Application (Client) ID**, **Directory (Tenant) ID** and the signed-in account of a Microsoft Entra ID connection +- Snowflake's **CLI Connection Name** and Spanner's **REST Endpoint** +- Beancount's **Run Ledger Plugins** +- **Use ~/.pgpass** and **Prompt for password** +- The SSL client key passphrase, and the pre-tunnel host and port +- **Pre-Connect Script** and **Post-Disconnect Script** + +Set them again on the imported connection. A credential profile new to this Mac arrives set to ask for its password; see [Credential Profiles](/connections/credential-profiles#sharing-and-sync). + +Startup SQL and tunnel commands run on every connect, so a file brings them only if you agree: importing lists each one and asks, and **Import Without Commands** is the default. A link's sheet shows its startup SQL in full before you add it. ## Share via link @@ -218,13 +231,13 @@ JSON, in format version 1 or 2. Saved queries and nested groups need version 2, } ``` -A `ref` links records inside one file and means nothing outside it. Refs must be unique within each kind. A ref that points at nothing, or a parent chain that loops, fails the import with an error naming the ref. +A `ref` links records inside one file and means nothing outside it. Refs must be unique within each kind. A ref that points at nothing, or a parent chain that loops, fails the import with an error naming the ref. So does an SSH tunnel whose host or user, or a jump host's, holds a character `ssh` refuses, such as a quote, a `;` or a leading `-`; that error names the connection. | Key | Holds | |---|---| | `groups` | Groups with a `ref`, a `name`, and an optional `color` and `iconName`, nested through `parentRef`. A connection points at the innermost one with `groupRef` | | `tags` | Tag colors. A connection lists its tags in `tagNames`, and a name missing here imports with no color | -| `credentialProfiles` | Profiles with `ref`, `name`, `username`, and `passwordMode` (`stored`, `prompt`, or `pgpass`), named by a connection's `credentialProfileRef`. A profile's password never travels, so a `stored` one imports as `prompt` | +| `credentialProfiles` | Profiles with `ref`, `name`, `username`, and `passwordMode` (`stored`, `prompt`, or `pgpass`), named by a connection's `credentialProfileRef`. A profile's password never travels, and a profile new to this Mac imports as `prompt` whatever its mode | | `queryFolders` | Saved query folders with a `ref` and a `name`, nested through `parentRef`. A `connectionRef` scopes a folder to that connection; without one it is global | | `savedQueries` | A `ref`, `name`, and `sql`, and an optional `keyword`, `folderRef`, and `connectionRef`. Without a `connectionRef` a query is global | | `credentials` | Only inside an encrypted file: secrets keyed by connection `ref` |