Infrastructure

Postgres

The Postgres event store, token store, dead-letter queue, scheduling, snapshots and transactions in @kronos-ts/postgres.

@kronos-ts/postgres stores the event log, processor tokens, dead letters, schedules and snapshots in Postgres, and gives every unit of work a Postgres transaction that your own handler statements can join. It sends raw SQL to the database, so it has no ORM, and it needs Postgres 14 or later.

You create one pool, start it, and pass it to each store and to the unit of work factory. The overview of infrastructure shows how these combine with other packages, and the Running on Postgres guide walks through a complete setup.

Connect

postgresPool takes a connection string and returns a pool. start() connects and creates the tables, and close() drains the pool on shutdown. Await start() before using the pool, because a statement sent earlier rejects with postgresPool: no connection yet.

// A connection string loads the `pg` driver when the pool starts.
export const pg = postgresPool(connectionString)
await pg.start()

// Drain the pool on shutdown.
await pg.close()

A connection string uses the pg driver (node-postgres), so install pg in your application. To use another driver, or to set the pool size, pass an adapter instead of a string. The package has an adapter for pg at @kronos-ts/postgres/adapters/pg, one for postgres (porsager) at @kronos-ts/postgres/adapters/postgres, and one for Bun.SQL at @kronos-ts/postgres/adapters/bun-sql. The Running on Postgres guide shows each one.

Schema

start() creates five tables with CREATE TABLE IF NOT EXISTS. Several instances can start together. A table that already exists is never altered, so you migrate an existing table yourself.

TableDefault nameHolds
Eventskronos_eventsThe event log
Snapshotskronos_snapshotsOne cached state per snapshot key
Scheduledkronos_scheduled_eventsEvents waiting to be appended
Tokenskronos_token_entriesOne row per processor segment
Dead letterskronos_dead_lettersEvents parked by dead lettering

Set other names once with the pool's tableNames option, and every store built on the pool uses them. Use plain unqualified names, and select a schema through the connection's search_path.

To create the tables with your own migration tool, pass bootstrap: false and run the DDL yourself. The pool then connects and creates nothing.

The package exports one DDL builder per table and index, such as buildEventsTableDDL(DEFAULT_TABLE_NAMES), and bootstrapSchema(pool) runs all of them.

Compose the stores

Each store is built from the pool. The scheduling and snapshot tiers wrap the event store, the token store and the dead-letter queue are separate, and postgresUnitOfWork makes every unit of work carry a transaction. The example wires all of them into one application.

const pg = postgresPool("postgresql://toolstore:secret@localhost:5432/toolstore")
await pg.start()

// Every unit of work the buses and processors mint carries a Postgres transaction.
const uow = postgresUnitOfWork(unitOfWork, pg)

// The log, then snapshots around it, then scheduling around that.
const eventStore = postgresSchedulingEventStore(
  postgresSnapshottingEventStore(postgresEventStore(pg), pg, jsonSerializer()),
  pg,
  uow,
)
const tokenStore = postgresTokenStore(pg, { claimTimeoutMs: 20_000 })
const deadLetters = postgresDeadLetterQueue(pg, { maxSequences: 256, maxSequenceSize: 64 })

// Commands run in the transactional factory. Queries run in the plain one.
const commandBus = localCommandBus(uow)
const queryBus = localQueryBus(unitOfWork)

Give the transactional factory to the command bus and to every event processor. Build the query bus from the plain unitOfWork, because a read needs no transaction: localQueryBus rejects the transactional factory with a compile error and an error at construction.

A processor reads from the event store, keeps its position in the token store, and parks failed events in the dead-letter queue:

const inventoryView = deadLettering(
  batched(eventProcessor("inventory-view", eventStore, tokenStore, uow), 200),
  deadLetters,
  byTool,
)

Event processors describes batching and dead lettering. The handler side of the two wrappers is described in Scheduling and Snapshots. A state declared with snapshot loads from the cached state in the snapshots table and replays only the events after it. Put an upcasting store outside the snapshot wrapper, so that upcasting applies to the events the cached read returns.

kronos() does not start the scheduling worker that appends due schedules. Call startScheduling() once the application is up, and stopScheduling() before closing the pool. polling and batched set the interval and the batch size. Several nodes can run the worker against one table.

// The scheduling worker is not started by kronos(). Tune it by wrapping the
// store, then start it.
const scheduler = polling(batched(eventStore, 100), 250)
await scheduler.startScheduling()

// On shutdown, in this order.
await scheduler.stopScheduling()
await pg.close()

Writing to your own tables

A handler that writes to its own tables declares PostgresCapability in its context type and reads ctx.sql(). At assembly, wrap the handler function with postgresHandler(handler, pg) and spread the entry. Wrapping a handler that does not declare sql() is a compile error. ctx.sql().query(sql, params) takes $1 style parameters, so pass user input as parameters and never concatenate it into the statement.

// In an event handler ctx.sql() is the batch's transaction: the write commits with the token.
export const markToolRented = eventHandler(
  ToolRented,
  async ({ payload }, ctx: EventHandlerContext & PostgresCapability) => {
    await ctx.sql().query("UPDATE inventory SET available = false WHERE tool_id = $1", [payload.toolId])
  },
)

What commits together depends on the kind of handler.

WriteIn a command handlerIn an event handler
Events from ctx.appendAppended at the end of the command, in one transactionNot applicable
ctx.schedule and ctx.cancelScheduleIn that transactionNot applicable
Statements on ctx.sql()On the pool, committed as each runs, before the events are appendedIn the batch's transaction
The processor's token update and dead lettersNot applicableIn the batch's transaction

In an event handler, the batch is the transaction. The statements of every handler in the batch, the token update and any dead letters commit or roll back together. A crash cannot advance the token and lose the write, and a batch that fails is delivered again from the old token, so a handler can run again for the same event after a rollback.

In a command handler, ctx.sql() is not atomic with the events the command appends. The handler's statements have already committed when the append runs, and a rejected append, such as a conflict, does not undo them. A retry runs them again, so write them idempotently, for instance as an upsert keyed by the entity's id.

// In a command handler ctx.sql() is the pool: the write commits as it runs.
export const registerCustomer = commandHandler(
  RegisterCustomer,
  async ({ payload }, ctx: CommandHandlerContext & PostgresCapability) => {
    await ctx.sql().query(
      `INSERT INTO customer_names (customer_id, name) VALUES ($1, $2)
       ON CONFLICT (customer_id) DO UPDATE SET name = EXCLUDED.name`,
      [payload.customerId, payload.name],
    )
    ctx.append(CustomerRegistered, payload)
  },
)

export const app = kronos({
  commandHandlers: [
    {
      ...registerCustomer,
      handler: postgresHandler(registerCustomer.handler, pg),
      eventStore,
      commandBus,
      queryBus,
    },
  ],
})

The guarantee for event handlers holds only when the token store, the dead-letter queue, postgresHandler and postgresUnitOfWork are built from the same pool. A client you create for the projection uses another connection, and so another transaction. ctx.sql().unwrap() returns the driver's own handle on the connection of the current transaction, so bind a query builder to it and never to a pool of its own. The handle is valid only while the transaction is open.

Outside postgresHandler, postgresTransaction(ctx.unitOfWork) returns the unit of work's transaction and opens it if it has not begun. It rejects for a unit of work that postgresUnitOfWork did not make.

Do not call postgresTransaction(ctx.unitOfWork) from a command handler. It holds a connection for the rest of the handler, and a ctx.load after it waits for a second connection from the same pool. When as many commands run at once as the pool has connections, each waits for a connection that another holds, and none finishes.

When the handler runs inside otlpHandler, each statement on ctx.sql() is recorded as a db.statement span with the statement text and no parameters.

Options

postgresPool takes these options after the connection string or adapter.

Prop

Type

start() retries a failed connect with exponential backoff and throws the last error when the attempts run out. Set the policy with the pool's resilience option: maxAttempts (default 10), initialDelayMs (100), maxDelayMs (30000), isRetryable to give up at once on an error that retrying cannot fix, and log, called before each retry. The policy covers start-up only, so a later lost connection is an unavailable error.

pgAdapter takes connectionString, poolConfig (the pg.Pool options, such as max, with a default pool size of 10) and the two timeouts above. The other adapters take connectionString and the timeouts.

// The adapter form picks a different driver or tunes the pool.
export const tuned = postgresPool(
  pgAdapter({
    connectionString,
    poolConfig: { max: 40 },
    idleInTransactionTimeoutMs: 15_000,
    statementTimeoutMs: 60_000,
  }),
  {
    tableNames: {
      events: "toolstore_events",
      snapshots: "toolstore_snapshots",
      scheduled: "toolstore_scheduled",
      tokens: "toolstore_tokens",
      deadLetters: "toolstore_dead_letters",
    },
    resilience: { maxAttempts: 20, maxDelayMs: 10_000 },
  },
)

An open transaction holds back every processor that reads the log, so the idle timeout ends one that stalls. A handler that does slow work that is not a database statement between two statements of a batch can exceed it and lose the batch's transaction. Raise the timeout or move the slow work out of the handler.

postgresTokenStore(pg, options):

Prop

Type

postgresDeadLetterQueue(pg, options):

Prop

Type

The scheduling worker's interval and batch size are set with polling(store, ms), default 1000, and batched(store, size), default 50.

Errors

ErrorCause and action
AppendConditionError from an append, with isConflict(error) trueThe events the command depended on changed, and nothing was written. Retry the command. A repeated event identifier fails the same way.
An error marked unavailable, with isUnavailable(error) trueThe server is unreachable, shutting down, out of connections, or a timeout fired. Retry later.
start() throws the last connection errorThe database was not reachable within the retry policy. Check the connection string and the server.
postgresPool: no connection yetA statement ran before start() resolved. Await start().
An error naming postgresUnitOfWorkA token store, dead-letter queue, schedule call or postgresTransaction got a unit of work without a Postgres transaction. Build the command bus and the processors from postgresUnitOfWork.
UnableToClaimTokenErrorAnother node holds the processor segment, or this node lost its claim during a pause. The batch fails and the processor claims again.
DeadLetterQueueOverflowErrorA group reached maxSequences or maxSequenceSize. The batch fails and is delivered again. Replay or clear the parked letters.
NoActiveUnitOfWork from scheduleschedule was called outside a handler.
The database ends a session after idleInTransactionTimeoutMsThe unit of work fails. Raise the idle timeout or move slow work out of the handler.

On this page