PgStateProvider
PgStateProvider<
TTxContext> =object
Defined in: packages/postgres/src/state-provider/state-provider.pg.ts:13
PostgreSQL state provider interface.
Abstracts database client operations, providing context management, transaction handling,
and SQL execution. Users create their own implementation to integrate with their preferred
client (raw pg, Drizzle, Prisma, etc.).
Type Parameters
Section titled “Type Parameters”TTxContext
Section titled “TTxContext”TTxContext extends BaseTxContext
The transaction context type containing database client/connection info
Properties
Section titled “Properties”close?
Section titled “close?”
optionalclose?: () =>Promise<void>
Defined in: packages/postgres/src/state-provider/state-provider.pg.ts:72
Releases provider-owned resources. Optional — pass-through providers (postgres.js, user-owned pool) can omit it. When defined, must be idempotent.
Returns
Section titled “Returns”Promise<void>
executeSql
Section titled “executeSql”executeSql: (
options) =>Promise<unknown[]>
Defined in: packages/postgres/src/state-provider/state-provider.pg.ts:57
Executes a SQL query. When txCtx is provided, uses that transaction connection. When txCtx is omitted, acquires a connection from the pool, executes, and releases.
id is a stable cache key for server-side prepared statements. It uniquely
identifies the resolved SQL within this provider instance (the adapter folds
template variants like schema / tablePrefix into the suffix), so providers
MAY use it directly as the prepared-statement name (pg: query.name = id) or
as a flag to opt into driver-level caching (postgres.js: prepare: true).
When omitted, the provider must execute the statement unprepared — the
adapter omits id for one-off or dynamic SQL (e.g. savepoints).
paramTypes / columnTypes are type hints for drivers that don’t auto-serialize/parse
(e.g. postgres.js unsafe()). Drivers that handle these natively (e.g. pg) can ignore.
readOnly indicates whether the statement reads only (pure SELECT with no FOR UPDATE).
Providers can use this to route to a read replica or a separate reader pool. The built-in
pool/postgres-js providers ignore it.
Parameters
Section titled “Parameters”options
Section titled “options”columnTypes
Section titled “columnTypes”Record<string, RuntimeType>
string
params
Section titled “params”unknown[]
paramTypes
Section titled “paramTypes”Record<number, RuntimeType>
readOnly
Section titled “readOnly”boolean
string
txCtx?
Section titled “txCtx?”TTxContext
Returns
Section titled “Returns”Promise<unknown[]>
transactionConcurrency
Section titled “transactionConcurrency”transactionConcurrency:
"concurrent"|"serialized"
Defined in: packages/postgres/src/state-provider/state-provider.pg.ts:18
Whether two withTransaction callbacks can run concurrently against the
underlying database.
withSavepoint?
Section titled “withSavepoint?”
optionalwithSavepoint?: <T>(txCtx,fn) =>Promise<T>
Defined in: packages/postgres/src/state-provider/state-provider.pg.ts:35
Executes a callback within a savepoint inside an existing transaction. Creates a savepoint, executes the callback, releases on success, rolls back to the savepoint on error.
Optional. When not provided, the adapter uses raw SAVEPOINT SQL via executeSql. Override when the driver tracks transaction state client-side (e.g. postgres.js).
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”TTxContext
(txCtx) => Promise<T>
Returns
Section titled “Returns”Promise<T>
withTransaction
Section titled “withTransaction”withTransaction: <
T>(fn) =>Promise<T>
Defined in: packages/postgres/src/state-provider/state-provider.pg.ts:25
Executes a callback within a database transaction. Acquires a connection, starts a transaction, executes the callback, commits on success, rolls back on error, and releases the connection.
Type Parameters
Section titled “Type Parameters”T
Parameters
Section titled “Parameters”(txCtx) => Promise<T>
Returns
Section titled “Returns”Promise<T>