docs: document the PGPROXY_TLS_MODE default and client impact

TLS is offered by default (optional) when a certificate is installed; required
is an explicit migration step because sslmode=disable clients (node-postgres
ssl:false and the loopback dogfood DSNs) otherwise fail with 08P01.

src/content/docs/clients/postgresql.md

@@ -8,7 +8,7 @@ PizzaSQL implements a **partial** PostgreSQL wire protocol, which lets *some* Po
 Before you connect anything, two facts matter:
 
 - **The SQL is SQLite-style, not PostgreSQL.** The dialect differences in [Compatibility](/sql-reference/compatibility/) apply to every client.
-- **TLS terminates at the managed proxy when the deployment enables it.** Use `sslmode=require` (or `verify-full` with a trusted, hostname-matching certificate). If the proxy declines SSL negotiation, the deployment has not installed a certificate yet: use `sslmode=disable` only over a trusted hop, and do not send sensitive data over an untrusted network. TLS never covers the proxy-to-engine loopback hop.
+- **TLS terminates at the managed proxy when the deployment enables it.** With a certificate installed, the proxy offers TLS by default (mode `optional`): `sslmode=prefer`/`require` clients upgrade automatically and existing `sslmode=disable` clients keep working. The operator can set `PGPROXY_TLS_MODE=required` to reject plaintext with `08P01`; clients pinned to `sslmode=disable` (including `ssl: false` in node-postgres) then fail until they enable TLS. If SSL negotiation is declined, the deployment has not installed a certificate yet: use `sslmode=disable` only over a trusted hop. TLS never covers the proxy-to-engine loopback hop.
 
 The connection parameters are described in [Connect](/getting-started/connect/):
 

src/content/docs/guides/limits.md

@@ -59,7 +59,13 @@ Imports of existing SQLite databases skip several constructs: views, triggers, p
 
 ## TLS and connectivity
 
-The managed PostgreSQL proxy supports TLS termination and can require it (`PGPROXY_REQUIRE_TLS` rejects plaintext with `08P01`). When the deployment has a certificate installed, connect with `sslmode=require` (or `verify-full`). If SSL negotiation is declined, that deployment has not enabled TLS yet and only `sslmode=disable` works; use it only over a trusted hop. The HTTP surface is HTTPS-only. TLS ends at the proxy: the loopback hop to PizzaSQL is plaintext. See the security notes in [API keys & permissions](/clients/api-keys/).
+The managed PostgreSQL proxy supports TLS termination with a deployment setting (`PGPROXY_TLS_MODE`):
+
+- `optional` (default when a certificate is installed) offers TLS; `sslmode=prefer`/`require` clients upgrade, while `sslmode=disable` clients keep working.
+- `required` rejects plaintext startup with `08P01`. Clients pinned to `sslmode=disable` or `ssl: false` must be updated first.
+- `off` disables TLS even if certificate paths are configured.
+
+If SSL negotiation is declined, that deployment has no certificate installed and only `sslmode=disable` works; use it only over a trusted hop. The HTTP surface is HTTPS-only. TLS ends at the proxy: the loopback hop to PizzaSQL is plaintext. See the security notes in [API keys & permissions](/clients/api-keys/) and the client impact matrix in [PostgreSQL clients](/clients/postgresql/#discovery-and-quota-errors).
 
 ## Related
 

src/content/docs/sql-reference/compatibility.md

@@ -216,7 +216,7 @@ Because the wire is PostgreSQL-compatible, drivers may issue introspection queri
 The managed database.pizza proxy layers additional behavior on top of PizzaSQL:
 
 - API keys with `read`, `write`, `alter_table`, and `drop_table` scopes gate statements.
-- PostgreSQL TLS terminates at the managed proxy when `PGPROXY_TLS_CERT`/`PGPROXY_TLS_KEY` are configured. Clients can use `sslmode=require` (or `verify-full` with a trusted, hostname-matching certificate). When `PGPROXY_REQUIRE_TLS=true`, plaintext startup is rejected with `08P01`. If a deployment has not installed certificates, `SSLRequest` is declined and only `sslmode=disable` connects; use that only over a trusted hop. TLS ends at the proxy — the loopback hop to PizzaSQL is plaintext.
+- PostgreSQL TLS terminates at the managed proxy when `PGPROXY_TLS_CERT`/`PGPROXY_TLS_KEY` are configured. `PGPROXY_TLS_MODE=optional` (the default with a certificate) offers TLS while keeping `sslmode=disable` clients working; `required` rejects plaintext startup with `08P01`; `off` disables TLS. Clients can use `sslmode=require` (or `verify-full` with a trusted, hostname-matching certificate). If a deployment has not installed certificates, `SSLRequest` is declined and only `sslmode=disable` connects; use that only over a trusted hop. TLS ends at the proxy — the loopback hop to PizzaSQL is plaintext.
 - Exhausting the per-organization connection quota returns SQLSTATE `53300` with the current/limit numbers and a retry hint. Quota and idle-connection behavior are documented in [Limits & quotas](/guides/limits/#connections-and-idle-disconnects).
 - The PostgreSQL database name is `org/db`; the slash must be percent-encoded in a URI.
 - Transaction statements are rejected by the managed HTTP query endpoints and forwarded by the PostgreSQL proxy.