feat: add PostgreSQL wake-ups

Author: cardmagic

CHANGELOG.md

@@ -31,6 +31,8 @@
 - Add PostgreSQL 14+ through the optional `pg` driver with pooled transactions,
   row-locked sequence allocation, portable schema and set queries, diagnostics,
   and real-server integration coverage.
+- Add opt-in role-specific PostgreSQL wake-ups with one event-driven listener
+  per runtime and polling as the correctness fallback.
 
 ## 0.1.0 - 2026-08-13
 

README.md

@@ -140,6 +140,11 @@ const database = postgresql({
   connectionString,
   maximumConnections: 10,
 })
+
+const runtime = configureSolidObjects({
+  database,
+  wakeUp: database.wakeUp(),
+})
 ```
 
 PostgreSQL uses a bounded `pg` pool, 64-bit database timestamps and sequences,
@@ -148,6 +153,13 @@ SQLite. Keep `pg` at 8.23 or newer within the supported major. Portable
 `DatabaseConnection` SQL uses `?` parameters; write `??` when a PostgreSQL query
 needs the literal JSON existence operator.
 
+`database.wakeUp()` is opt-in. It uses one event-driven PostgreSQL client per
+runtime to listen on role-specific channels and wake every matching local
+waiter. Create it in every process that should send or receive notifications.
+Polling remains the fallback if a notification is missed or the listener
+reconnects. Because `LISTEN` is session-scoped, use a direct connection or
+session pooling rather than transaction pooling for this client.
+
 Authorization is deny-by-default. Actor IDs identify actors; they are not
 capabilities.
 
@@ -158,9 +170,10 @@ instances to finish, so no replacement can outlive the runtime.
 
 The default in-process wake-up adapter interrupts role polling as soon as this
 runtime commits new work. Polling remains the correctness fallback, so a missed
-or failed signal costs latency rather than losing work. Multi-process hosts can
-provide a `WakeUpAdapter` backed by their existing notification system without
-adding a required broker to the default SQLite stack.
+or failed signal costs latency rather than losing work. Multi-process hosts not
+using PostgreSQL notifications can provide a `WakeUpAdapter` backed by their
+existing notification system without adding a required broker to the default
+SQLite stack.
 
 ## Call it like a local object
 

docs/architecture.md

@@ -35,6 +35,13 @@ transaction on one checked-out client, stores timestamps and sequences as
 64-bit integers, and locks an actor's instance row while allocating mailbox
 sequences. Both adapters use database time and the same fencing predicates.
 
+PostgreSQL notifications are an opt-in latency layer. One event-driven client
+per runtime listens on role-specific channels before the worker checks durable
+state, which closes the listener-startup race without Ruby's connection per
+blocking thread. A notification advances a process-local role generation and
+wakes every matching waiter. Reconnection and notification loss fall back to
+the ordinary polling interval.
+
 A worker claims one actor globally, then preferentially drains up to
 `maxMessagesPerActivationPass` ready turns for that instance. Reaching the cap
 moves only that actor's already-due ready memberships to current database time.

docs/parity.md

@@ -54,14 +54,15 @@ Reference: Ruby `solid_objects` 0.12.0 at commit `a01b6f5`.
 
 ## Databases and wake-up
 
-| Capability                   | Status  | TypeScript shape or remaining work                                                                                                                                     |
-| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| SQLite                       | Native  | Uses built-in `node:sqlite`, serialized process-local access, foreign keys, strict tables, and database time.                                                          |
-| PostgreSQL                   | Native  | Optional `pg` 8.23 peer, bounded pooling, 64-bit schema, row-locked sequence allocation, portable set queries, server checks, and a real PostgreSQL integration suite. |
-| MySQL                        | Planned | Add a driver-neutral pool interface, MySQL schema, locking behavior, integration suite, engine/version checks, and client compatibility tests.                         |
-| Durable polling fallback     | Native  | Every role progresses without a notification service.                                                                                                                  |
-| In-process wake-up           | Native  | A generation-based default adapter prevents claim-to-wait signal loss; commits wake role-specific waiters and polling remains the fallback.                            |
-| PostgreSQL and Redis wake-up | Planned | Add optional adapters; neither may become a hidden required dependency.                                                                                                |
+| Capability               | Status  | TypeScript shape or remaining work                                                                                                                                     |
+| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite                   | Native  | Uses built-in `node:sqlite`, serialized process-local access, foreign keys, strict tables, and database time.                                                          |
+| PostgreSQL               | Native  | Optional `pg` 8.23 peer, bounded pooling, 64-bit schema, row-locked sequence allocation, portable set queries, server checks, and a real PostgreSQL integration suite. |
+| MySQL                    | Planned | Add a driver-neutral pool interface, MySQL schema, locking behavior, integration suite, engine/version checks, and client compatibility tests.                         |
+| Durable polling fallback | Native  | Every role progresses without a notification service.                                                                                                                  |
+| In-process wake-up       | Native  | A generation-based default adapter prevents claim-to-wait signal loss; commits wake role-specific waiters and polling remains the fallback.                            |
+| PostgreSQL wake-up       | Native  | `database.wakeUp()` uses one dedicated event-driven client, role-specific `LISTEN/NOTIFY`, generation fencing, reconnectable listeners, and durable polling fallback.  |
+| Redis wake-up            | Planned | Add an optional Pub/Sub adapter without making Redis a hidden required dependency.                                                                                     |
 
 ## Realtime and browser behavior
 

src/broadcast-worker.ts

@@ -37,7 +37,7 @@ export class BroadcastWorker {
   async run(signal: AbortSignal): Promise<void> {
     await this.ensureRegistered()
     while (!signal.aborted && !this.stopping) {
-      const wakeUp = this.runtime.settings.wakeUp.watch("broadcasts")
+      const wakeUp = await this.runtime.settings.wakeUp.watch("broadcasts")
       const processed = await this.runOnce()
       if (processed === 0) {
         await wakeUp.wait({

src/database/postgresql.ts

@@ -1,6 +1,14 @@
 import { Pool, TypeOverrides, types, type PoolClient, type PoolConfig } from "pg"
 import { postgresqlSql } from "./postgresql-sql.js"
 import type { Database, DatabaseConnection, RunResult } from "./types.js"
+import { PostgreSQLWakeUpAdapter, type PostgreSQLWakeUpFailure } from "../wake-up/postgresql.js"
+
+export {
+  PostgreSQLWakeUpAdapter,
+  postgresqlWakeUp,
+  type PostgreSQLWakeUpFailure,
+  type PostgreSQLWakeUpOptions,
+} from "../wake-up/postgresql.js"
 
 export interface PostgreSQLDatabaseOptions {
   connectionString: string
@@ -11,6 +19,12 @@ export interface PostgreSQLDatabaseOptions {
   onPoolError?: (error: Error) => void
 }
 
+export interface PostgreSQLDatabaseWakeUpOptions {
+  channelPrefix?: string
+  applicationName?: string
+  onListenerError?: (failure: PostgreSQLWakeUpFailure) => void
+}
+
 class PostgreSQLConnection implements DatabaseConnection {
   constructor(private readonly client: PoolClient) {}
 
@@ -46,12 +60,14 @@ export class PostgreSQLDatabase implements Database {
   readonly family = "postgresql" as const
   readonly schemaIdentity = "solid-objects-node-v1"
   private readonly pool: Pool
+  private readonly connectionString: string
   private closed = false
 
   constructor(options: PostgreSQLDatabaseOptions) {
     if (options.connectionString.length === 0) {
       throw new TypeError("PostgreSQL connectionString must not be empty")
     }
+    this.connectionString = options.connectionString
     if (
       options.maximumConnections !== undefined &&
       (!Number.isSafeInteger(options.maximumConnections) || options.maximumConnections < 1)
@@ -125,6 +141,13 @@ export class PostgreSQLDatabase implements Database {
     this.closed = true
     await this.pool.end()
   }
+
+  wakeUp(options: PostgreSQLDatabaseWakeUpOptions = {}): PostgreSQLWakeUpAdapter {
+    return new PostgreSQLWakeUpAdapter({
+      connectionString: this.connectionString,
+      ...options,
+    })
+  }
 }
 
 function postgresqlTypes(): TypeOverrides {

src/effect-worker.ts

@@ -37,7 +37,7 @@ export class EffectWorker {
   async run(signal: AbortSignal): Promise<void> {
     await this.ensureRegistered()
     while (!signal.aborted && !this.stopping) {
-      const wakeUp = this.runtime.settings.wakeUp.watch("effects")
+      const wakeUp = await this.runtime.settings.wakeUp.watch("effects")
       const processed = await this.runOnce()
       if (processed === 0) {
         await wakeUp.wait({

src/reminder-scheduler.ts

@@ -50,7 +50,7 @@ export class ReminderScheduler {
   async run(signal: AbortSignal): Promise<void> {
     await this.ensureRegistered()
     while (!signal.aborted && !this.stopping) {
-      const wakeUp = this.runtime.settings.wakeUp.watch("reminders")
+      const wakeUp = await this.runtime.settings.wakeUp.watch("reminders")
       const processed = await this.runOnce()
       if (processed === 0) {
         await wakeUp.wait({

src/wake-up.ts

@@ -10,7 +10,7 @@ export interface WakeUpWatch {
 }
 
 export interface WakeUpAdapter {
-  watch(role: WakeUpRole): WakeUpWatch
+  watch(role: WakeUpRole): WakeUpWatch | Promise<WakeUpWatch>
   notify(role: WakeUpRole): void | Promise<void>
   close(): void | Promise<void>
 }