From c9aaa7bad5d884f0ebaf44ab09152105a35b5a2d Mon Sep 17 00:00:00 2001 From: Ngo Quoc Dat Date: Thu, 12 Nov 2026 12:59:14 +0700 Subject: [PATCH] docs(connections): Vault database roles share one user per profile and wait for a new one to load --- connections/credential-profiles.mdx | 6 ++++-- features/connection-sharing.mdx | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/connections/credential-profiles.mdx b/connections/credential-profiles.mdx index f891dd6..2d05615 100644 --- a/connections/credential-profiles.mdx +++ b/connections/credential-profiles.mdx @@ -62,9 +62,11 @@ A role on Vault's database secrets engine hands out a new database user for ever | Vault Address | The server, such as `https://vault.example.com:8200`. Leave it empty to use `VAULT_ADDR` | | Sign In With | **Token** reads `VAULT_TOKEN`, then `~/.vault-token` from `vault login`. **AppRole** takes a role ID and a file holding the secret ID. **OIDC** opens your browser once per launch | -The username field greys out, because Vault generates the username too. **Test Source** reads a lease, shows the username and password it got, and revokes it. +The username field greys out, because Vault generates the username too. **Test Source** shows the username and password the profile's connections sign in with, and reads a lease when none is held. -Each sign-in reads a new lease, so the main connection, a second database, and a backup each sign in as a user of their own. While connected, the lease renews before it expires. When Vault stops renewing it, at the role's maximum TTL or when renewal fails, the connection signs in again with a new lease before the old user is revoked. Disconnecting revokes the lease. The generated password stays in memory: it never reaches the Keychain, `connections.json`, or iCloud. +Everything on one profile signs in as one database user: the main connection, a second database, a backup, and a test. A backup tool that takes the password on its command line, such as SqlPackage, gets a user of its own, revoked when the backup ends. While in use, the lease renews before it expires. When Vault stops renewing it, at the role's maximum TTL or when renewal fails, the connection signs in again with a new lease. The lease is revoked when the last connection using it disconnects, after 10 minutes with nothing using it, and at quit, which waits up to 3 seconds for Vault. The generated password stays in memory: it never reaches the Keychain, `connections.json`, or iCloud. + +Some databases refuse a user Vault has just created until they load it, such as Vitess or ProxySQL reloading users on a timer, or a MySQL replica catching up. When a MySQL-family server answers a new user with access denied (error 1045), the connect tries the same user again until 30 seconds after Vault created it, and the connection window shows *Waiting for the database to accept the new Vault user*. If the database still refuses it, the next attempt uses the same user. Any refused sign-in also asks Vault, by renewing the lease, whether it still exists, and a lease Vault no longer has is replaced on the next sign-in. A MySQL-family user the database accepted before and now refuses with error 1045 is replaced too, since Vault renews it without asking the database. On other engines, a user dropped in the database while Vault still has its lease stays in use until every connection on the profile disconnects. An OIDC role must allow the redirect URI `http://localhost:8250/oidc/callback`, the one `vault login -method=oidc` uses. A connection that needs an OIDC sign-in offers **Sign In** instead of failing. diff --git a/features/connection-sharing.mdx b/features/connection-sharing.mdx index ab8d613..2e6d710 100644 --- a/features/connection-sharing.mdx +++ b/features/connection-sharing.mdx @@ -209,7 +209,7 @@ A connection in `~/Library/Application Support/TablePro/connections.json` can sa | `onePassword` | `op read` on the reference | `op signin` | | `vault` | `vault kv get` for one field at a path | `VAULT_ADDR` and `VAULT_TOKEN` in TablePro's environment | | `awsSecretsManager` | `aws secretsmanager get-secret-value`. `jsonKey` pulls one field out of a JSON secret; omit it for the whole value | | -| `vaultDatabaseRole` | A new lease from `/creds/`, which supplies the username as well. `auth.method` is `token` (the default), `approle` with `roleId` and `secretIdPath`, or `oidc` with an optional `role`; each takes an optional `mount` | `address`, or `VAULT_ADDR` in TablePro's environment. See [Vault database roles](/connections/credential-profiles#vault-database-roles) | +| `vaultDatabaseRole` | A lease from `/creds/`, shared by this connection's sign-ins, which supplies the username as well. `auth.method` is `token` (the default), `approle` with `roleId` and `secretIdPath`, or `oidc` with an optional `role`; each takes an optional `mount` | `address`, or `VAULT_ADDR` in TablePro's environment. See [Vault database roles](/connections/credential-profiles#vault-database-roles) | Every command gets 30 seconds. The three CLI kinds quote each argument, so a reference cannot break out into the shell, and they need the tool on `PATH`, in `/usr/local/bin`, or in `/opt/homebrew/bin`.