Rulvar API reference / @rulvar/store-postgres / PostgresStore
Class: PostgresStore
Defined in: packages/store-postgres/src/store.ts:129
@rulvar/store-postgres: PostgresStore implementing JournalStore and LeasableStore with fencing epochs over node-postgres, for multi-process and multi-host deployments (RV-214). Payloads stay opaque TEXT (A4); every run-scoped mutation serializes on a per-run advisory transaction lock so the fence check and the guarded mutation commit as one unit across hosts. Beside it, PostgresQuotaLimiter (RV410) is the multi-host reference of the core QuotaLimiter SPI: one database, one schema, one global provider quota, admission serialized on a schema-wide advisory lock.
Implements
Constructors
Constructor
new PostgresStore(options): PostgresStore;Defined in: packages/store-postgres/src/store.ts:159
Parameters
| Parameter | Type |
|---|---|
options | PostgresStoreOptions |
Returns
PostgresStore
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
effectLane | readonly | true | Effect lane capability (plan 45, rfcs/effects.md section 4.5, item 3): the restoration generation lives OUTSIDE the journal bytes in the same schema. The restore runbook is one rule: after a point-in-time restore, run bumpRestorationGeneration() BEFORE the restored database becomes reachable to any worker, so the effect lane comes up with dispatch disabled until an operator appends a fresh effect_epoch citing the bumped generation. | packages/store-postgres/src/store.ts:141 |
fencedWrites | readonly | true | The fenced writes promise (fenced run state RFC, phase 2). | packages/store-postgres/src/store.ts:131 |
Accessors
leaseTtlMs
Get Signature
get leaseTtlMs(): number;Defined in: packages/store-postgres/src/store.ts:622
TTL introspection (the LeasableStore optional capability).
Returns
number
Optional TTL introspection (v1.35.0 review P2-4): the configured lease ttl in milliseconds. A store exposing it lets createWorker VERIFY at construction that the worker's renew cadence matches the store's expiry instead of trusting two config sources to agree; stores without it are accepted with the worker's own ttl.
Implementation of
Methods
acquire()
acquire(runId, owner): Promise<Lease>;Defined in: packages/store-postgres/src/store.ts:626
Parameters
| Parameter | Type |
|---|---|
runId | string |
owner | string |
Returns
Promise<Lease>
Implementation of
append()
append(
runId,
e,
lease?): Promise<void>;Defined in: packages/store-postgres/src/store.ts:443
Parameters
| Parameter | Type |
|---|---|
runId | string |
e | JournalEntry |
lease? | Lease |
Returns
Promise<void>
Implementation of
bumpRestorationGeneration()
bumpRestorationGeneration(): Promise<number>;Defined in: packages/store-postgres/src/store.ts:332
The restore procedure's one mutation (plan 45, rfcs/effects.md section 4.5, item 3): after a point-in-time restore, bump the generation BEFORE the restored database becomes reachable to any worker, so the effect lane comes up with dispatch disabled until an operator appends a fresh effect_epoch citing the bumped generation. Every extra bump only widens the fence.
Returns
Promise<number>
close()
close(): Promise<void>;Defined in: packages/store-postgres/src/store.ts:309
Returns
Promise<void>
delete()
delete(runId, lease?): Promise<void>;Defined in: packages/store-postgres/src/store.ts:540
Parameters
| Parameter | Type |
|---|---|
runId | string |
lease? | Lease |
Returns
Promise<void>
Implementation of
getMeta()
getMeta(runId): Promise<RunMeta | undefined>;Defined in: packages/store-postgres/src/store.ts:486
Parameters
| Parameter | Type |
|---|---|
runId | string |
Returns
Promise<RunMeta | undefined>
Implementation of
listRuns()
listRuns(f?): Promise<RunMeta[]>;Defined in: packages/store-postgres/src/store.ts:495
Parameters
| Parameter | Type |
|---|---|
f? | RunFilter |
Returns
Promise<RunMeta[]>
Implementation of
load()
load(runId): Promise<JournalEntry[]>;Defined in: packages/store-postgres/src/store.ts:457
Parameters
| Parameter | Type |
|---|---|
runId | string |
Returns
Promise<JournalEntry[]>
Implementation of
putMeta()
putMeta(m, lease?): Promise<void>;Defined in: packages/store-postgres/src/store.ts:476
Parameters
| Parameter | Type |
|---|---|
m | RunMeta |
lease? | Lease |
Returns
Promise<void>
Implementation of
release()
release(l): Promise<void>;Defined in: packages/store-postgres/src/store.ts:670
Parameters
| Parameter | Type |
|---|---|
l | Lease |
Returns
Promise<void>
Implementation of
renew()
renew(l): Promise<void>;Defined in: packages/store-postgres/src/store.ts:658
Parameters
| Parameter | Type |
|---|---|
l | Lease |
Returns
Promise<void>
Implementation of
restorationGeneration()
restorationGeneration(): Promise<number>;Defined in: packages/store-postgres/src/store.ts:314
The current restoration generation; 0 until a restore ever ran.
Returns
Promise<number>
Implementation of
EffectLaneStore.restorationGeneration
transcripts()
transcripts(): PostgresTranscriptStore;Defined in: packages/store-postgres/src/store.ts:559
The fenced transcript twin (RFC F2): blobs live in this store's database beside the lease rows, so a lease-carrying put or delete verifies the current holder of the run the ref's leading path segment names atomically with the blob mutation. Wire it as the engine's transcript store next to this store as the journal; assertFencedWrites({ journal, transcripts }) verifies the pair.