postgres

Classes

PostgresStorage

Defined in: src/storage/postgres.storage.ts:110

Postgres-backed implementation of IdempotencyStorage.

Stores each record as a row in idempotency_records (override via tableName). Atomic NX is enforced by the primary-key constraint on key combined with INSERT ... ON CONFLICT DO UPDATE WHERE expires_at <= now(). Token-based compare-and-set is enforced by WHERE token = $ clauses on complete() and delete(). Lazy expiration is enforced by WHERE expires_at > now() in get().

For active cleanup of expired rows see PostgresSweepService.

Implements

• IdempotencyStorage
• OnModuleDestroy

Constructors

Constructor

new PostgresStorage(options): PostgresStorage;

Defined in: src/storage/postgres.storage.ts:116

Parameters

Parameter	Type
options	PostgresStorageOptions

Returns

PostgresStorage

Methods

close()

close(): Promise<void>;

Defined in: src/storage/postgres.storage.ts:265

Returns

Promise<void>

complete()

complete(
   key,
   token,
   response,
ttlSeconds): Promise<MutateResult>;

Defined in: src/storage/postgres.storage.ts:201

Transitions a PROCESSING record to COMPLETED and stores the captured response, but ONLY if the record is unexpired and its token matches the caller's. Returns 'stale' for missing/expired records, token mismatches, and an already COMPLETED record (including the same token). A stale operation must not overwrite a response or refresh TTL.

On 'ok', implementations must refresh the TTL to ttlSeconds.

Parameters

Parameter	Type	Description
key	string	-
token	string	-
response	CompleteResponse	-
ttlSeconds	number	completed record lifetime, an integer in [1, 2_147_483_647] seconds

Returns

Promise<MutateResult>

Throws

RangeError if ttlSeconds is invalid, before ownership or state checks

Implementation of

IdempotencyStorage.complete

create()

create(
   key,
   fingerprint,
ttlSeconds): Promise<CreateResult>;

Defined in: src/storage/postgres.storage.ts:171

Atomically creates a PROCESSING record. On success, returns an opaque token that the caller MUST pass back to complete() / delete(). An expired record is absent for NX purposes, regardless of physical cleanup.

Parameters

Parameter	Type	Description
key	string	the idempotency key from the client header (already scoped by the interceptor to include endpoint identity)
fingerprint	string | undefined	SHA-256 of the request body, or undefined if fingerprinting is off
ttlSeconds	number	lifetime of the lock, an integer in [1, 2_147_483_647] seconds

Returns

Promise<CreateResult>

Throws

RangeError if ttlSeconds is invalid, before NX or expiry checks

Implementation of

IdempotencyStorage.create

createSchema()

static createSchema(pool, tableName?): Promise<void>;

Defined in: src/storage/postgres.storage.ts:280

Idempotently creates the records table and supporting index. Safe to call multiple times. Used by autoCreateSchema=true and available as a public helper for code-driven migrations.

Parameters

Parameter	Type	Default value
pool	Pool	undefined
tableName	string	DEFAULT_TABLE_NAME

Returns

Promise<void>

delete()

delete(key, token): Promise<MutateResult>;

Defined in: src/storage/postgres.storage.ts:240

Removes a record, but ONLY if the caller's token matches. Returns 'ok' if the record was removed OR was absent/expired (idempotent cleanup), and 'stale' only if a DIFFERENT record (with a different token) is currently stored and unexpired under this key. Expired physical rows may remain for later cleanup; delete success does not promise immediate physical removal.

Parameters

Parameter	Type
key	string
token	string

Returns

Promise<MutateResult>

Implementation of

IdempotencyStorage.delete

get()

get(key): Promise<IdempotencyRecord | null>;

Defined in: src/storage/postgres.storage.ts:138

Fetches a record by key. Returns null if the key does not exist or has expired.

Parameters

Parameter	Type
key	string

Returns

Promise<IdempotencyRecord | null>

Implementation of

IdempotencyStorage.get

onModuleDestroy()

onModuleDestroy(): Promise<void>;

Defined in: src/storage/postgres.storage.ts:271

Returns

Promise<void>

Implementation of

OnModuleDestroy.onModuleDestroy

onModuleInit()

onModuleInit(): Promise<void>;

Defined in: src/storage/postgres.storage.ts:132

Returns

Promise<void>

---

PostgresSweepService

Defined in: src/services/postgres-sweep.service.ts:38

Optional service that periodically deletes expired idempotency records.

Lazy expiration in PostgresStorage.get already guarantees correctness; this service exists only to keep disk usage and dead tuples bounded in long-running deployments.

Multi-instance safety: each sweep wraps DELETE in pg_try_advisory_lock(hashtext('idempotency-sweep')). Concurrent replicas will see a lock contention and skip — no DELETE storms.

Implements

• OnModuleInit
• OnModuleDestroy

Constructors

Constructor

new PostgresSweepService(storage, options?): PostgresSweepService;

Defined in: src/services/postgres-sweep.service.ts:42

Parameters

Parameter	Type
storage	PostgresStorage
options	SweepOptions

Returns

PostgresSweepService

Methods

onModuleDestroy()

onModuleDestroy(): Promise<void>;

Defined in: src/services/postgres-sweep.service.ts:61

Returns

Promise<void>

Implementation of

OnModuleDestroy.onModuleDestroy

onModuleInit()

onModuleInit(): Promise<void>;

Defined in: src/services/postgres-sweep.service.ts:52

Returns

Promise<void>

Implementation of

OnModuleInit.onModuleInit

sweep()

sweep(): Promise<{
  deleted: number;
}>;

Defined in: src/services/postgres-sweep.service.ts:69

Runs one sweep cycle. Returns the number of rows deleted (0 if another replica holds the advisory lock for this cycle).

Returns

Promise<{ deleted: number; }>

Interfaces

PostgresStorageOptions

Defined in: src/storage/postgres.storage.ts:22

Constructor options for PostgresStorage.

Provide either a pre-built pool (recommended — lets the consumer manage connection lifecycle) OR a connection config that the storage uses to lazily build its own pool.

Properties

autoCreateSchema?

optional autoCreateSchema?: boolean;

Defined in: src/storage/postgres.storage.ts:38

If true, run CREATE TABLE IF NOT EXISTS and matching index on module init. Defaults to false. Recommended only for development.

connection?

optional connection?: PoolConfig;

Defined in: src/storage/postgres.storage.ts:26

pg PoolConfig used to lazily construct an internal pool.

pool?

optional pool?: Pool;

Defined in: src/storage/postgres.storage.ts:24

A pre-built pg Pool. Wins over connection if both are supplied.

poolFactory?

optional poolFactory?: (connection) => Pool;

Defined in: src/storage/postgres.storage.ts:28

Test-only seam: custom factory used in place of new Pool(connection).

Parameters

Parameter	Type
connection	PoolConfig

Returns

Pool

tableName?

optional tableName?: string;

Defined in: src/storage/postgres.storage.ts:33

Table name used for idempotency records.

Default

'idempotency_records'

---

SweepOptions

Defined in: src/services/postgres-sweep.service.ts:17

Properties

enabled

enabled: boolean;

Defined in: src/services/postgres-sweep.service.ts:19

When false, the service is wired up but never schedules a sweep.

intervalMs?

optional intervalMs?: number;

Defined in: src/services/postgres-sweep.service.ts:21

Sweep cadence. Defaults to 60_000 (1 minute).