docs(databases): connect to PostgreSQL through a Unix socket

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).
 

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.
 

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
   <img className="hidden dark:block" src="/images/postgresql-connection-form-dark.png" alt="PostgreSQL connection form" />
 </Frame>
 
+## 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