Postgres API
Generated public TypeScript reference for @relkit/postgres.
For configuration and examples, read postgres, railway, vercel.
Public imports
@relkit/postgres— 15 exports@relkit/postgres/runtime— 24 exports@relkit/postgres/drizzle— 4 exports
All exported APIs
Names link to their complete contracts. Re-exports share their original contract; legacy exports keep their separate identity. Examples link to the API’s inline sample, a maintained repository usage, or the shared module walkthrough.
index.ts
“./outbox.js” (namespace export)
Re-exports all named exports from the “./outbox.js” module.
Signature
export * from "./outbox.js";
outbox.ts
Transactional outbox for Drizzle. outbox(tx).publish(event, payload)
validates the payload against the event contract and writes the envelope
and its per-consumer deliveries with one statement on the caller’s Drizzle
transaction, so the event commits or rolls back with the transaction’s other
writes. Consumers run later from the Postgres event provider’s loops.
“./outbox.types.js” (namespace export)
Re-exports all named exports from the “./outbox.types.js” module.
Signature
export * from "./outbox.types.js";
outbox
Binds the outbox to a Drizzle transaction (or database) on the backend’s Postgres database.
Example
await db.transaction(async (tx) => outbox(tx).publish(orderPlaced, { orderId }));
Signature
declare const outbox: <Result>(
transaction: OutboxTransaction<Result>,
options?: OutboxOptions,
) => PostgresOutbox;
outbox.types.ts
Contracts of the Drizzle transactional outbox.
OutboxOptions (interface)
Outbox settings; they must match the event provider’s profile and tables. @experimental
Signature
export interface OutboxOptions extends PostgresTableOptions {
/** Event profile used when the event contract names none; defaults to `default`. */
readonly profile?: string;
}
OutboxTransaction (interface)
Anything with Drizzle’s execute(sql): a Postgres database or transaction. @experimental
Signature
export interface OutboxTransaction<Result> {
readonly execute: (query: SQL) => PromiseLike<Result>;
}
PostgresOutbox (interface)
The outbox bound to one transaction. @experimental
Signature
export interface PostgresOutbox {
/**
* Writes one event on the bound transaction.
* @param event - Event contract; the payload is validated against its schema.
* @param payload - Event payload.
* @param options - Optional ordering key and attributes.
* @returns The persisted envelope; consumers see it only if the transaction commits.
*/
readonly publish: <Id extends string, Version extends number, Input>(
event: EventDescriptor<Id, Version, Input>,
payload: Input,
options?: EventPublishOptions,
) => Promise<UnknownEventEnvelope & { readonly eventId: Id; readonly version: Version }>;
}
events-envelope.ts
Builds the event envelope that publication persists in the outbox. Both the
provider’s publish and the Drizzle outbox use it, so an event written
inside an application transaction is indistinguishable from one published
directly. Pure construction; no connection is opened.
createEventEnvelope
Creates a new envelope for one publication.
Example
createEventEnvelope("orders.placed", 1, { orderId: "o-1" }).instanceId.startsWith("event-");
Signature
declare const createEventEnvelope: (
eventId: string,
version: number,
payload: UnknownEventEnvelope["payload"],
options?: EventPublishOptions,
propagation?: TracePropagation,
) => UnknownEventEnvelope;
index.ts
“./events-envelope.js” (namespace export)
Re-exports all named exports from the “./events-envelope.js” module.
Signature
export * from "./events-envelope.js";
“./providers.js” (namespace export)
Re-exports all named exports from the “./providers.js” module.
Signature
export * from "./providers.js";
“./schema.js” (namespace export)
Re-exports all named exports from the “./schema.js” module.
Signature
export * from "./schema.js";
providers.ts
Authoring entry for the Postgres backend. postgresJob() and postgresEvent()
build the provider adapters an application selects in defineApp({ jobs, events }).
They validate options and serialize connection and behavior data only; the
runtime entry opens connections when the application starts.
“./providers.types.js” (namespace export)
Re-exports all named exports from the “./providers.types.js” module.
Signature
export * from "./providers.types.js";
PostgresEventAdapter (type alias)
Events provider adapter selected with postgresEvent(). @experimental
Signature
type PostgresEventAdapter = ProviderAdapter<typeof event, "postgres-event">;
PostgresJobAdapter (type alias)
Jobs provider adapter selected with postgresJob(). @experimental
Signature
type PostgresJobAdapter = ProviderAdapter<typeof job, "postgres-job">;
postgresConnectionContract
Connection fields both adapters accept. @experimental
Signature
declare const postgresConnectionContract: ProviderConnectionContract;
postgresEvent
Selects durable Postgres events with per-consumer delivery for an events profile.
Throws
TypeError for unknown options or an invalid URL, identifier or duration.
Example
const events = postgresEvent