Function pgBackend

Create a Postgres-backed idempotency cache.

Pass a connection pool (or any PgQueryable) and optionally a custom table name. Run getIdempotencyMigration() once per deployment to create the table.

Multi-agent namespace. The official serve() path automatically adds its canonical host to the idempotency principal before this backend sees a key. Low-level integrations that bypass serve() and can receive the same principal/key on multiple logical agents MUST use distinct tableName values (or separate schemas/databases). Construct one store per logical agent and pass the matching store to that agent's server factory:

await pool.query(getIdempotencyMigration({ tableName: 'seller_a_idempotency' }));
const sellerAIdempotency = createIdempotencyStore({
  backend: pgBackend(pool, { tableName: 'seller_a_idempotency' }),
});
Copy

Reusing one table without an equivalent trusted host discriminator can replay one agent's cached response on another when their server-controlled principal and buyer key collide.

Startup probe. Call store.probe() (or probeIdempotencyStore(store)) before your server starts accepting traffic to catch a bad DATABASE_URL at boot rather than on the first mutating request. Wire it via:

serve(createAgent, {
  readinessCheck: () => store.probe(),
});
Copy

Idle-client errors. pg.Pool re-emits network drop / PG restart errors on the pool itself. Without a listener, Node's EventEmitter default-throws and crashes the process. Add one in your bootstrap:

pool.on('error', (err) => console.error('pg pool error', err));
Copy