docs(databases): Kerberos sign-in for PostgreSQL and MariaDB

databases/mariadb.mdx

@@ -16,6 +16,14 @@ mariadb://user:password@localhost/database?socket=%2Ftmp%2Fmysql.sock
 
 `socket` works as it does on [MySQL](/databases/mysql#connection-url). See [Connection URL Reference](/connections/urls).
 
+## Kerberos
+
+For an account created `IDENTIFIED VIA gssapi`, set **Authentication** to **Kerberos (GSSAPI)** and set **Username** to the account name. Leave **Kerberos Principal** and **Password** blank to use the ticket in your credential cache, or enter `user@REALM.COM` and your domain password to have one requested at connect. Get a cached ticket with `kinit user@REALM.COM`.
+
+The server names its own service principal, set in `gssapi_principal_name`, and this Mac has to reach the realm's KDC. The option appears on MariaDB connections only: MySQL's Kerberos plugin is a different one, which the bundled connector does not have.
+
+Any other **Authentication** refuses an account `IDENTIFIED VIA gssapi` with `This account signs in with Kerberos.`, so a connection never signs in with a ticket it was not set up for.
+
 ## Differences from MySQL
 
 - The default authentication plugin is `mysql_native_password`, against `caching_sha2_password` on MySQL 8. Both connect.

databases/mssql.mdx

@@ -42,7 +42,7 @@ On macOS, Windows Authentication means Kerberos. Set **Authentication** to **Win
 
 Four things have to hold:
 
-- Connect by hostname, never an IP address. Kerberos targets the service principal name `MSSQLSvc/host.domain.com:1433`, registered against the host name.
+- Connect by hostname, never an IP address. Kerberos targets the service principal name `MSSQLSvc/host.domain.com:1433`, registered against the host name. Through an SSH tunnel it still names that host and port.
 - Write the realm in uppercase, usually the DNS domain: `CONTOSO.COM`.
 - This Mac has to reach the domain's KDC, through DNS SRV records or `/etc/krb5.conf`.
 - The SQL Server service account has to own that SPN. Your administrator registers it.

databases/postgresql.mdx

@@ -1,6 +1,6 @@
 ---
 title: PostgreSQL
-description: Connect to PostgreSQL 9.1 and later with the libpq driver, including PostGIS display, AWS and Google Cloud IAM auth, and pg_dump backups
+description: Connect to PostgreSQL 9.1 and later with the libpq driver, including PostGIS display, AWS and Google Cloud IAM and Kerberos auth, and pg_dump backups
 ---
 
 import DeclaredColumnType from "/snippets/declared-column-type.mdx";
@@ -75,6 +75,14 @@ Set **Authentication** to an AWS IAM option and set **Username** to a database r
 
 For a Cloud SQL instance you reach directly, set **Authentication** to a Google Cloud IAM option and set **Username** to the IAM database user. See [IAM sign-in without the proxy](/connections/cloud-sql-proxy#iam-sign-in-without-the-proxy).
 
+### Kerberos
+
+For a server whose `pg_hba.conf` line uses `gss`, set **Authentication** to **Kerberos (GSSAPI)** and set **Username** to the role the server maps your principal to. Leave **Kerberos Principal** and **Password** blank to use the ticket in your credential cache, or enter `user@REALM.COM` and your domain password to have one requested at connect. Get a cached ticket with `kinit user@REALM.COM`; `klist` shows it.
+
+Connect by hostname, never an IP address: the ticket is for the service principal `postgres/host.domain.com@REALM.COM`, registered against the host name. Through an SSH tunnel the ticket is still for that host name. This Mac has to reach the realm's KDC, through DNS SRV records or `/etc/krb5.conf`.
+
+**GSS Encryption** sets libpq's `gssencmode`: **Preferred** encrypts the session with Kerberos when the server allows it, **Required** refuses a server that does not, **Disabled** never tries. A session encrypted this way skips TLS, so SSL Mode applies only when GSS encryption is not used. Any other sign-in never tries GSS encryption.
+
 ### 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.
@@ -182,6 +190,7 @@ New connections default to **Preferred** (libpq `sslmode=prefer`): TLS first, pl
 - Columns cannot be reordered. The structure editor adds, renames, retypes, and drops; changing the order of existing columns means recreating the table.
 - Session state belongs to one database. A temp table or an open transaction made on `app` is not visible from a tab on `logs`, and closing the `app` entry ends it, after asking first when a transaction is open.
 - Backup and restore need `pg_dump` and `pg_restore` on your Mac. Neither is bundled; install them with Homebrew. `pg_dump` 15 and later refuse PostgreSQL 9.1, so back one up with `pg_dump` 14 or earlier.
+- With Kerberos, backup and restore use the ticket in your credential cache, never one requested from **Kerberos Principal** and **Password**. Run `kinit` first.
 - Before PostgreSQL 12, the [`run_maintenance`](/developers/mcp-tools) tool's `REINDEX` with no `table` runs without `CONCURRENTLY` and rebuilds the system catalog indexes as well. While an index rebuilds, writes to its table wait, and so do reads that use that index. Run it when the database is quiet.
 
 ## Troubleshooting
@@ -190,6 +199,12 @@ New connections default to **Preferred** (libpq `sslmode=prefer`): TLS first, pl
 
 **FATAL: password authentication failed for user "…"**: the role and password are checked against `pg_hba.conf`. Confirm the method on the matching line (`scram-sha-256` or `md5` for passwords, `trust` for local dev), and that the line matches the host you are connecting from.
 
+**No Kerberos ticket was found.**: the credential cache holds no ticket. Run `kinit user@REALM.COM`, or fill in **Kerberos Principal** and **Password**, then reconnect. **The Kerberos ticket has expired.** asks for the same.
+
+**The PostgreSQL Kerberos service principal is not registered.**: the KDC does not know `postgres/host.domain.com`. Ask your administrator to register it in the realm, and connect by the host name it is registered under. macOS keeps that answer for up to 20 minutes, so a reconnect right after the principal is registered can still fail; quitting TablePro clears it.
+
+**This server signs in with Kerberos.**: the server's `pg_hba.conf` line uses `gss`, and **Authentication** is set to something else. Set it to **Kerberos (GSSAPI)**.
+
 **ERROR: invalid byte sequence for encoding "UTF8": 0x…**: the database's encoding is `SQL_ASCII`, which stores bytes without checking them, and a value in the result is not UTF-8. Run `SHOW server_encoding` to confirm. Move the data to a `UTF8` database: dump it with `pg_dump --encoding=` and the encoding the text was written in, such as `EUC_JP` or `WIN1252`, then restore that dump into a database created with `ENCODING 'UTF8'`.
 
 **A Postgres-compatible engine loads no tables**: wire-compatible engines connect under the PostgreSQL type, and the catalogs they omit are probed for rather than assumed. An engine without `pg_matviews` still lists its tables. One missing a catalog, function or column the listing reads loses table comments first, then falls back to `information_schema.tables`: tables and views appear, each partition as a table of its own, and materialized views and foreign tables do not.