diff --git a/connections/connection-form.mdx b/connections/connection-form.mdx index f36c71f0..a7f74b68 100644 --- a/connections/connection-form.mdx +++ b/connections/connection-form.mdx @@ -25,10 +25,10 @@ The bar along the bottom carries **Test Connection**, **Cancel** and **Save**, p |-------|-------------| | **Name** | Display name in the connection list | | **Type** | The database type. **Change…** retypes the connection and resets the fields the old type owned | -| **Connect Using** | MySQL and MariaDB. **Host and Port**, or **Socket** for a server on this Mac. See [Unix socket](/databases/mysql#unix-socket) | +| **Connect Using** | MySQL, MariaDB, and PostgreSQL. **Host and Port**, or **Socket** for a server on this Mac. See Unix socket for [MySQL](/databases/mysql#unix-socket) and [PostgreSQL](/databases/postgresql#unix-socket) | | **Host** | Empty falls back to the driver's own default, usually `localhost` | | **Port** | Pre-filled from the database type | -| **Socket** | Replaces Host and Port when **Connect Using** is **Socket**. The full path of the server's socket file, such as `/tmp/mysql.sock` | +| **Socket** | Replaces Host when **Connect Using** is **Socket**. MySQL and MariaDB take the socket file, such as `/tmp/mysql.sock`, and drop Port. PostgreSQL takes the folder, such as `/tmp`, and keeps Port, which names the file | | **Database** | Optional on drivers that browse every database from one session. PostgreSQL and Redshift do not connect without one | | **Username** | Not pre-filled. Empty means the driver's own default | | **Password** | Stored in the macOS Keychain | @@ -53,7 +53,7 @@ SQLite, DuckDB, libSQL, and Beancount replace the host fields with a file path. Leave it on **Direct** unless the database is unreachable from this Mac. Switching to another transport keeps what you typed into the previous one, so switching back costs nothing. -A connection set to **Socket** on General offers only **Direct**, since a tunnel cannot reach a socket file on this Mac. +A connection set to **Socket** on General offers only **Direct**, since a tunnel cannot reach a socket file on this Mac. A PostgreSQL socket also has no SSL settings. **Socket Path**, under **SSH Tunnel**, forwards to a unix socket instead of Host and Port, which are then unused. See [Forwarding to a unix socket](/connections/ssh-tunneling#forwarding-to-a-unix-socket). diff --git a/connections/urls.mdx b/connections/urls.mdx index 68f7b512..4157e7f2 100644 --- a/connections/urls.mdx +++ b/connections/urls.mdx @@ -116,6 +116,7 @@ Names are matched case-insensitively. Anything unrecognized is ignored, except o | `statusColor` | Connection color as hex, matched to the nearest palette color | `?statusColor=FF3B30` | | `env` | Assign an existing tag by name. `environment` is accepted too | `?env=production` | | `socket` | MySQL and MariaDB. Socket file path, in place of host and port. Alias `unix_socket`. See [Unix socket](#unix-socket) | `?socket=%2Ftmp%2Fmysql.sock` | +| `host`, `port` | PostgreSQL. Override the URL's own host and port. A host starting with `/` is the socket folder. See [PostgreSQL socket](#postgresql-socket) | `?host=/var/run/postgresql` | ### Unix socket @@ -133,6 +134,22 @@ mariadb://root@/shop?socket=(/tmp/mysql.sock) - Other engines and `+ssh` URLs ignore `socket`. - **Copy Connection String** writes this form, with no port. +### PostgreSQL socket + +```text +postgresql://user@localhost:5433/shop?host=/var/run/postgresql +postgresql:///shop?host=%2Ftmp&port=5433 +postgresql://%2Ftmp:5433/shop +``` + +- A host starting with `/` is the folder holding the socket, as in `psql`. Write it in `host=`, or percent-encoded in place of the host. +- `host=` and `port=` win over the host and port before the path. +- The port picks the socket file, `.s.PGSQL.5433` for `5433`. A host naming that file sets the port from its name. +- Only `%` escapes decode: `+` stays a `+`. +- A folder with a comma, a control or invisible character, or a socket file path over 103 bytes refuses the URL. +- `socket` is not read: it is MySQL's name. +- **Copy Connection String** writes the first form, with the port when it is not `5432`. + ### SSL/TLS | Parameter | Values | Description | @@ -237,7 +254,7 @@ When another client also handles the scheme, `open -b com.TablePro "mysql://…" Every URL opened from outside the app raises an **Open External Database Connection?** alert naming the database type, host and port or socket, user, and database. **Connect** does not answer the Return key. Escape is the only keyboard answer, and it cancels. -**Always Allow** appears only for a database on this machine (`localhost`, `127.x.x.x`, `::1`, or a socket). A trusted link is matched on database type, host, socket, database, username, and the URL's `name` parameter, never the port, so the same link on a different port still connects without asking again. Trusting `localhost` does not cover a socket link. Trusting one socket does not cover another. Remote hosts always prompt, and so does a link through an SSH tunnel, whose database is on the SSH server. +**Always Allow** appears only for a database on this machine (`localhost`, `127.x.x.x`, `::1`, or a socket). A trusted link is matched on database type, host, socket, database, username, and the URL's `name` parameter, never the port, so the same link on a different port still connects without asking again. Trusting `localhost` does not cover a socket link. Trusting one socket does not cover another, and a PostgreSQL socket on another port is another socket. Remote hosts always prompt, and so does a link through an SSH tunnel, whose database is on the SSH server. A link with a [filter](#filtering) asks every time and offers no **Always Allow**. Read the filter in the box under the target before choosing **Connect**: it runs on the table as soon as the connection opens. diff --git a/databases/postgresql.mdx b/databases/postgresql.mdx index b1b5525c..8a309278 100644 --- a/databases/postgresql.mdx +++ b/databases/postgresql.mdx @@ -11,9 +11,11 @@ Unlike MySQL, PostgreSQL will not connect without a **Database**, and a connecti | Field | Default | Notes | |-------|---------|-------| +| **Connect Using** | **Host and Port** | **Socket** connects through the server's socket on this Mac. See [Unix socket](#unix-socket) | | **Host** | `localhost` | | -| **Port** | `5432` | | -| **Username** | - | Not pre-filled; most servers use `postgres` | +| **Port** | `5432` | With **Socket**, picks the socket file | +| **Socket** | empty | With **Connect Using** set to **Socket**: the folder holding the socket, or the socket file | +| **Username** | - | Not pre-filled; most servers use `postgres`. Empty signs in as your macOS login name | | **Database** | - | **Required** | Fill in the form and click **Save & Connect**. For remote servers use [SSH tunneling](/connections/ssh-tunneling); Google Cloud SQL instances can connect through the [Cloud SQL Auth Proxy](/connections/cloud-sql-proxy). @@ -32,13 +34,36 @@ Any server from 9.1 on works. A feature the server predates stays out of the sid PostgreSQL connection form +## Unix socket + +A server on this Mac listens on a socket as well as a port, and a server with `listen_addresses = ''` listens only there. Set **Connect Using** to **Socket** and enter the folder that holds the socket. Host leaves the form, and **Network** offers only **Direct**. + +The socket file is named after the port, `.s.PGSQL.5432` for port `5432`, so **Port** stays and picks the server. Entering the file itself, such as `/tmp/.s.PGSQL.5433`, saves its folder and sets **Port** from the name. The server lists its folders: + +```sql +SHOW unix_socket_directories; +``` + +| Where | Folder | +|-------|--------| +| Homebrew, Postgres.app | `/tmp` | +| Debian and Ubuntu packages | `/var/run/postgresql` | + +The **Socket** field suggests both. The note under it names the socket file and says when nothing is there. Save still works, so a connection can be set up before its server starts. A path starting with `~` is expanded, and macOS caps the socket file's path at 103 bytes. + +A `local` line in `pg_hba.conf` decides who signs in. With `peer`, leave **Username** empty to sign in as your macOS login name. + +No SSL Mode applies: a socket connection never leaves this Mac, so the SSL settings leave the Network tab. Backup and restore reach the server through the same socket, and `~/.pgpass` matches it the way `psql` does: the `/tmp` folder as `localhost`, any other folder by its path. + ## Connection URL ```text postgresql://user:password@host:5432/database +postgresql://user@localhost:5433/database?host=/var/run/postgresql +postgresql://user@%2Ftmp/database ``` -`postgres://` also works. Opening a URL connects directly. See [Connection URL Reference](/connections/urls). +`postgres://` also works. A host starting with `/`, in `host=` or percent-encoded in place of the host, is the socket folder. Opening a URL connects directly. See [Connection URL Reference](/connections/urls#postgresql-socket). ## Authentication @@ -52,7 +77,7 @@ For a Cloud SQL instance you reach directly, set **Authentication** to a Google ### 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. The form reports what it found, including `~/.pgpass has incorrect permissions (needs chmod 0600)`, the one that silently blocks a connect. +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. ## Databases and schemas