Installation#

One pool, four providers, and a schema you own.

Install#

pnpm add @sigx/actors-pg pg

npm install @sigx/actors-pg pg

yarn add @sigx/actors-pg pg

bun add @sigx/actors-pg pg

Postgres ≥ 13, pg ≥ 8.

Create the schema#

Tables live in one Postgres schema, sigx by default. DDL is explicit — the providers never issue it, so a production role needs only DML grants.

import pg from 'pg';
import { ensurePgSchema, pgSchemaSql } from '@sigx/actors-pg';

const pool = new pg.Pool({ connectionString: process.env.PG_URL });

await ensurePgSchema(pool);   // dev and tests

In production, emit the SQL and run it through your migration tool instead:

console.log(pgSchemaSql('sigx'));

Wire it up#

import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { pgCluster, pgReminders, pgStorage } from '@sigx/actors-pg';

export const app = defineActorApp({
    actors,
    storage: pgStorage({ pool }),
    reminders: pgReminders({ pool }),
}).use(cluster({
    providers: pgCluster({ pool }),
    advertise: `http://${process.env.POD_IP}:7311`,
    secret: process.env.HOST_SECRET,
}));

Every provider takes pool or url — with url, the package constructs its own pg.Pool. Sharing one pool is the point of this package.

Options#

Pool sizing#

Every provider shares the pool, and pgMembership() checks out a connection to hold LISTEN when it can. Size the pool with that in mind — a pool of one works, but pushes membership onto the poll path permanently.

Verify#

PG_URL=postgres://postgres:postgres@localhost:5432/postgres pnpm test -- actors-pg

The provider suite is env-gated on PG_URL; CI provides a postgres:16 service container and the rest of the matrix skips cleanly.

Next steps#

• API reference — exports, tables and semantics.
• Timers & reminders — what pgReminders() replaces.
• Storage — the seam pgStorage() implements.