docs(self-hosting): promote postgres from experimental to recommended OSS multi-node backend

[MasterPtato]

No description provided.

[MasterPtato]

Stack for rivet-dev/rivet

Current stack:

• [SLOP(claude-opus-4-8-high)] perf(universaldb): batch leader apply and fold follower commit round-trips #5342 vtrtqpyp · 2026-06-26 02:20:21
• [slopfix] docs(self-hosting): promote postgres from experimental to recommended OSS multi-node backend #5341 zsmysquk · 2026-06-26 02:20:19 👈
• [slopfix] fix(self-host): repair dev compose generation, kitchen-sink serverful runner, and postgres/udb bootstrap #5340 wpvkrymu · 2026-06-25 22:53:05
• [SLOP(claude-opus-4-8-high)] feat(universaldb): graceful postgres leader handoff on shutdown #5337 mvxpzxsl · 2026-06-25 20:34:04
• [slopfix] test(universaldb): postgres leader failover + abort resolver task on driver drop #5336 tvmntvqo · 2026-06-25 20:34:03
• [SLOP(claude-opus-4-8-high)] feat(ups): table-backed postgres transport with coalesced doorbell #5335 xutxrzrv · 2026-06-25 20:34:01
• [SLOP(claude-opus-4-8-high)] feat(universaldb): postgres leader-resolver driver overhaul #5329 xrrmomwz · 2026-06-25 00:55:07
• [SLOP(claude-opus-4-8)] feat(pegboard-envoy): rate-limit envoy ws ingress and cap get_pages, trim unused metrics #5327 tnzyzqrl · 2026-06-24 20:57:36
• [SLOP(claude-opus-4-8)] feat(util): add rate limiter primitive and ingress throttles for actor create and gateway websocket #5326 pnyswwtm · 2026-06-24 20:57:35
• [SLOP(claude-opus-4-8)] feat(rivetkit-core): add serde duration and size metrics #5322 nqkrytvr · 2026-06-23 22:49:13
• Add observation for serde_bare #5321 oskoutmw · 2026-06-23 20:23:10
• Add observation and ser/de metrics for serde calls #5320 ztnuwvts · 2026-06-23 20:23:09

Dependencies:

• [SLOP(claude-opus-4-8-medium)] fix(rivetkit-napi): reap completed tasks from event-loop JoinSet (#5315) #5314 xxqwtrzp · 2026-06-22 22:42:01
• main

Get stack: forklift get 5341
Push local edits: forklift submit
Merge when ready: forklift merge 5341

[claude]

Review: Promote PostgreSQL from Experimental to Recommended

This PR updates 12 documentation files to remove the "experimental" label from PostgreSQL and promote it as the production-ready backend for multi-node and multi-region self-hosted deployments. It also removes the unstable_disable_lock_customization config option from Supabase/PlanetScale examples (which was removed from the code), adds new Requirements/Recommendations content to postgres.mdx, and repositions NATS as optional rather than recommended.

---

website/src/content/docs/self-hosting/postgres.mdx — Missing migration note for removed unstable_disable_lock_customization (breaking upgrade for Supabase/PlanetScale users)

The old troubleshooting section explicitly told users to add unstable_disable_lock_customization: true to their Supabase and PlanetScale configs. The Supabase and PlanetScale config examples also showed this field. This PR removes both the field from the examples and the troubleshooting section that recommended it, without any upgrade note.

The underlying Postgres config struct (engine/packages/config/src/config/db/postgres.rs:34) uses #[serde(deny_unknown_fields)]. This means any user who followed the old docs and has unstable_disable_lock_customization: true in their production config will hit a hard deserialization error on the next Rivet upgrade — the engine will refuse to start with an "unknown field" error.

Suggested fix: Add a note in the Troubleshooting section (or a new "Upgrading" sub-section) like:

Removed option: If your config includes unstable_disable_lock_customization: true, remove it. This option no longer exists and Rivet will fail to start if it is present.

---

website/src/content/docs/self-hosting/production-checklist.mdx — NATS downgrade from "recommended" to "optional" should be verified against pub/sub latency guarantees

The previous checklist called NATS "recommended" for production because PostgreSQL LISTEN/NOTIFY "has limited throughput." The new text calls it "optional" and says PostgreSQL pub/sub is "sufficient for most deployments."

The PostgreSQL pub/sub implementation (engine/packages/universalpubsub/src/driver/postgres/mod.rs) does use a 1-second polling backstop (POLL_INTERVAL = Duration::from_secs(1)) as a correctness floor. NOTIFY is used as a fast-path doorbell, but if a NOTIFY is dropped or delayed, delivery falls back to the 1-second poll. For actors with tight wake/message latency requirements, this can mean worst-case 1-second latency in degraded conditions.

This is a reasonable trade-off to document, but the downgrading of NATS from "recommended" to "optional" is a notable change in guidance. If this is intentional based on production data showing PostgreSQL pub/sub is reliable enough, the checklist is fine. If there are known workloads (e.g. high-frequency actor wakeups) where NATS is still genuinely better, the "optional" framing may lead some production users to skip it.

---

Everything else looks clean

• The multi-region link added in the postgres.mdx Overview section resolves correctly (website/src/content/docs/self-hosting/multi-region.mdx exists).
• The connection limit formula of nodes × 150 is consistent with the code: each engine node has two deadpool pools of max_size: 64 (one in universaldb, one in universalpubsub) plus 1–2 dedicated listener connections, giving ~130 per node; the 150 multiplier adds reasonable headroom.
• All "experimental" references have been scrubbed across the 12 changed files — no orphaned occurrences remain.
• The <Warning> → <Note> changes, the new Requirements/Recommendations section, and the FoundationDB comparison table updates are all consistent with the promotion claim.