@b4run/postgres-storage

Use this when#Copy link to section: Use this when

Use this package when a deployed B4.run application needs shared durable checkpoints, Agent Protocol threads, and permission grants across instances. Each permissions-store instance caches grants and observes another instance's writes after its next load(). The root accepts a structural pool for Node or edge hosts. /node adds pg connection-string convenience.

Install and import#Copy link to section: Install and import

npm install @b4run/postgres-storage pg

import { createPostgresThreadsStore } from "@b4run/postgres-storage"
import { postgresCheckpointer } from "@b4run/postgres-storage/node"

Compatibility and audience#Copy link to section: Compatibility and audience

The edge-safe classification covers the root's import graph. It is tested on local workerd with a Neon WebSocket pool, not on every edge provider or a live Cloudflare deployment.

Public exports#Copy link to section: Public exports

@b4run/postgres-storage#Copy link to section: @b4run/postgres-storage

@b4run/postgres-storage/node#Copy link to section: @b4run/postgres-storage/node

The /node entry also re-exports every root export. The rows below list them again. Its three factories use the connection-string-aware implementations.

Key contracts#Copy link to section: Key contracts

PostgresStoreOptions#Copy link to section: PostgresStoreOptions

export interface PostgresStoreOptions {
  readonly pool?: SqlPool
  readonly ownsPool?: boolean
  readonly assumeMigrated?: boolean
  readonly schema?: string
  readonly tablePrefix?: string
}

Fields: @b4run/postgres-storage#.:PostgresStoreOptions

Although pool is optional in the shared type, root factories fail without one. Use /node when connectionString or standard pg environment defaults should create an owned pool.

export interface PostgresPermissionsStoreOptions extends PostgresStoreOptions {
  readonly config?: PermissionsFile
  readonly mode?: PermissionMode
}

export declare function postgresCheckpointer(
  options?: PostgresCheckpointerOptions,
): B4PostgresSaver

export declare function createPostgresThreadsStore(
  options?: PostgresThreadsStoreOptions,
): PostgresThreadsStore

export declare function createPostgresPermissionsStore(
  options?: PostgresPermissionsStoreOptions,
): PostgresPermissionsStore

export interface NodePostgresStoreOptions extends PostgresStoreOptions {
  readonly connectionString?: string
}

export interface NodePostgresPermissionsStoreOptions extends PostgresPermissionsStoreOptions {
  readonly connectionString?: string
}

export declare function postgresCheckpointer(
  options?: NodePostgresStoreOptions,
): B4PostgresSaver

export declare function createPostgresThreadsStore(
  options?: NodePostgresStoreOptions,
): PostgresThreadsStore

export declare function createPostgresPermissionsStore(
  options?: NodePostgresPermissionsStoreOptions,
): PostgresPermissionsStore

Behavior contract postgres-storage.migration.instance-scoped

Migration memoization belongs to each store instance; assumeMigrated skips that instance's migration pass, while an unflagged instance begins a locked transaction.

Behavior contract postgres-storage.entry-split

The main entry links without Node built-ins for edge pools, while /node deliberately fails an edge bundle because it imports pg for connectionString convenience.

Migration and pool ownership#Copy link to section: Migration and pool ownership

Migration state is instance-scoped. In a per-request host, migrate an unflagged cold set of all three components, then set assumeMigrated only for the same database, schema, prefix, component, and current package schema. A wrong assertion fails on the first query. Checkpoint, thread, and permission migrations are separate.

Another process sees a durable permission grant only after that store calls load(). When you construct a custom permissions store, pass the resolved mode and config explicitly. B4.run does not overlay sibling configuration onto an already-created store.

Do not mark every store as owning one shared pool. An injected pool defaults to caller-owned and receives no error listener from B4.run. Setting ownsPool: true makes that store end it. A /node factory-created pool is owned, monitored, and closed by that store.

Schemas, table prefixes, and thread IDs organize data, but they are not tenant authorization boundaries. Rows are plaintext unless your database and infrastructure provide encryption.

Examples and related guides#Copy link to section: Examples and related guides

import { Pool } from "pg"
import {
  createPostgresPermissionsStore,
  createPostgresThreadsStore,
  postgresCheckpointer,
} from "@b4run/postgres-storage"
 
const pool = new Pool({ connectionString: process.env.DATABASE_URL })
pool.on("error", (error) => console.warn("Postgres pool error", error))
const checkpointer = postgresCheckpointer({ pool })
const threadsStore = createPostgresThreadsStore({ pool })
const permissionsStore = createPostgresPermissionsStore({ pool })
await Promise.all([checkpointer.ready(), threadsStore.ready(), permissionsStore.ready()])
 
// During application shutdown:
await Promise.all([checkpointer.close(), threadsStore.close(), permissionsStore.close()])
await pool.end()

Continue with Persistence and Tenancy, Production Topology, and Edge and Hono.