PersistentAI API Documentation / @persistent-ai/fireflow-executor / server / PostgresExecutionStore

Class: PostgresExecutionStore

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:17

Implements

• IExecutionStore

Constructors

Constructor

new PostgresExecutionStore(db): PostgresExecutionStore

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:18

Parameters

db

NodePgDatabase<Record<string, unknown>> & object

Returns

PostgresExecutionStore

Methods

batchGetDirectChildren()

batchGetDirectChildren(parentIds): Promise<ChildFeedItem[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:479

Batch-fetch direct children of multiple parents in one query. Used by the chain auto-loader in TraceView: fetches single children of chain nodes.

Parameters

parentIds

string[]

Returns

Promise<ChildFeedItem[]>

Implementation of

IExecutionStore.batchGetDirectChildren

---

claimExecution()

claimExecution(executionId, workerId, timeoutMs): Promise<boolean>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:506

Claim an execution for a worker atomically Uses PostgreSQL row-level locking to ensure only one worker can claim an execution Also updates the execution's processing fields in the same transaction

Parameters

executionId

string

workerId

string

timeoutMs

number

Returns

Promise<boolean>

Implementation of

IExecutionStore.claimExecution

---

create()

create(row): Promise<void>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:22

Parameters

row

completedAt

Date | null

createdAt

Date

errorMessage

string | null

errorNodeId

string | null

executionDepth

number

externalEvents

object[] | null

failureCount

number

flowId

string

id

string

integration

object & object | null

lastFailureAt

Date | null

lastFailureReason

string | null

options

{ breakpoints?: string[]; debug?: boolean; execution?: { flowTimeoutMs?: number; maxConcurrency?: number; nodeTimeoutMs?: number; }; } | null

ownerId

string

parentExecutionId

string | null

processingStartedAt

Date | null

processingWorkerId

string | null

rootExecutionId

string | null

startedAt

Date | null

status

ExecutionStatus

updatedAt

Date

Returns

Promise<void>

Implementation of

IExecutionStore.create

---

delete()

delete(id): Promise<boolean>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:52

Parameters

id

string

Returns

Promise<boolean>

Implementation of

IExecutionStore.delete

---

expireOldClaims()

expireOldClaims(): Promise<number>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:709

Expire old claims that have passed their expiration time

Returns

Promise<number>

Implementation of

IExecutionStore.expireOldClaims

---

extendClaim()

extendClaim(executionId, workerId, timeoutMs): Promise<boolean>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:641

Extend an execution claim (heartbeat)

Parameters

executionId

string

workerId

string

timeoutMs

number

Returns

Promise<boolean>

Implementation of

IExecutionStore.extendClaim

---

get()

get(id): Promise<{ completedAt: Date | null; createdAt: Date; errorMessage: string | null; errorNodeId: string | null; executionDepth: number; externalEvents: object[] | null; failureCount: number; flowId: string; id: string; integration: object & object | null; lastFailureAt: Date | null; lastFailureReason: string | null; options: { breakpoints?: string[]; debug?: boolean; execution?: { flowTimeoutMs?: number; maxConcurrency?: number; nodeTimeoutMs?: number; }; } | null; ownerId: string; parentExecutionId: string | null; processingStartedAt: Date | null; processingWorkerId: string | null; rootExecutionId: string | null; startedAt: Date | null; status: ExecutionStatus; updatedAt: Date; } | null>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:38

Parameters

id

string

Returns

Promise<{ completedAt: Date | null; createdAt: Date; errorMessage: string | null; errorNodeId: string | null; executionDepth: number; externalEvents: object[] | null; failureCount: number; flowId: string; id: string; integration: object & object | null; lastFailureAt: Date | null; lastFailureReason: string | null; options: { breakpoints?: string[]; debug?: boolean; execution?: { flowTimeoutMs?: number; maxConcurrency?: number; nodeTimeoutMs?: number; }; } | null; ownerId: string; parentExecutionId: string | null; processingStartedAt: Date | null; processingWorkerId: string | null; rootExecutionId: string | null; startedAt: Date | null; status: ExecutionStatus; updatedAt: Date; } | null>

Implementation of

IExecutionStore.get

---

getActiveClaims()

getActiveClaims(): Promise<ExecutionClaim[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:665

Get all active claims

Returns

Promise<ExecutionClaim[]>

Implementation of

IExecutionStore.getActiveClaims

---

getChildExecutions()

getChildExecutions(parentId): Promise<object[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:202

Get all child executions of a parent

Parameters

parentId

string

Returns

Promise<object[]>

Implementation of

IExecutionStore.getChildExecutions

---

getChildFeed()

getChildFeed(rootExecutionId, limit, cursor?): Promise<{ items: ChildFeedItem[]; nextCursor: string | null; }>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:286

Get a cursor-paginated feed of child executions for a root execution. Returns newest-first. Used by the Execution Feed UI.

Parameters

rootExecutionId

string

limit

number

cursor?

Date

Returns

Promise<{ items: ChildFeedItem[]; nextCursor: string | null; }>

Implementation of

IExecutionStore.getChildFeed

---

getClaimForExecution()

getClaimForExecution(executionId): Promise<ExecutionClaim | null>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:684

Get claim for a specific execution

Parameters

executionId

string

Returns

Promise<ExecutionClaim | null>

Implementation of

IExecutionStore.getClaimForExecution

---

getDirectChildFeed()

getDirectChildFeed(parentExecutionId, limit, cursor?): Promise<{ items: ChildFeedItem[]; nextCursor: string | null; }>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:440

Get a cursor-paginated feed of DIRECT children of a specific execution. Used by the TraceView children panel (works at any depth, not just root executions).

Parameters

parentExecutionId

string

limit

number

cursor?

Date

Returns

Promise<{ items: ChildFeedItem[]; nextCursor: string | null; }>

Implementation of

IExecutionStore.getDirectChildFeed

---

getExecutionsNeedingRecovery()

getExecutionsNeedingRecovery(limit?): Promise<object[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:755

Get executions that need recovery Finds executions that are:

1. Status = 'created' but no active claim
2. Status = 'running' but claim expired
3. Status = 'created' with failureCount < 5 and lastFailureAt > 1 minute ago

Parameters

limit?

number = 1000

Returns

Promise<object[]>

Implementation of

IExecutionStore.getExecutionsNeedingRecovery

---

getExecutionStats()

getExecutionStats(rootExecutionId): Promise<ExecutionStats>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:351

Get aggregate stats for a root execution's entire subtree. Used by the Execution Feed UI to show throughput and status counts.

Parameters

rootExecutionId

string

Returns

Promise<ExecutionStats>

Implementation of

IExecutionStore.getExecutionStats

---

getExecutionTree()

getExecutionTree(executionId): Promise<ExecutionTreeNode[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:215

Get the execution subtree rooted at executionId. Works for both root executions (depth=0) and non-root executions (depth>0). For non-root executions, fetches the full tree by rootExecutionId first, then traverses downward from executionId.

Parameters

executionId

string

Returns

Promise<ExecutionTreeNode[]>

Implementation of

IExecutionStore.getExecutionTree

---

getRecoveryHistory()

getRecoveryHistory(executionId): Promise<object[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:823

Get recovery history for an execution

Parameters

executionId

string

Returns

Promise<object[]>

Implementation of

IExecutionStore.getRecoveryHistory

---

getRootExecutions()

getRootExecutions(flowId, limit?, after?): Promise<RootExecution[]>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:122

Parameters

flowId

string

limit?

number = 50

after?

Date | null

Returns

Promise<RootExecution[]>

Implementation of

IExecutionStore.getRootExecutions

---

recordRecovery()

recordRecovery(executionId, workerId, reason, previousStatus?, previousWorkerId?): Promise<void>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:803

Record a recovery action for an execution

Parameters

executionId

string

workerId

string

reason

string

previousStatus?

string

previousWorkerId?

string

Returns

Promise<void>

Implementation of

IExecutionStore.recordRecovery

---

releaseExecution()

releaseExecution(executionId, workerId): Promise<void>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:607

Release an execution claim Also clears the processing fields in the execution row

Parameters

executionId

string

workerId

string

Returns

Promise<void>

Implementation of

IExecutionStore.releaseExecution

---

releaseRecoveryLock()

releaseRecoveryLock(lockId): Promise<void>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:851

Release a PostgreSQL advisory lock

Parameters

lockId

number

Returns

Promise<void>

Implementation of

IExecutionStore.releaseRecoveryLock

---

tryAcquireRecoveryLock()

tryAcquireRecoveryLock(lockId): Promise<boolean>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:835

Try to acquire a PostgreSQL advisory lock Returns true if lock was acquired, false if another session holds it

Parameters

lockId

number

Returns

Promise<boolean>

Implementation of

IExecutionStore.tryAcquireRecoveryLock

---

updateExecutionStatus()

updateExecutionStatus(params): Promise<boolean>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:65

Atomically update execution status and related fields This method avoids the need to fetch the execution first

Parameters

params

UpdateExecutionStatusParams

Returns

Promise<boolean>

Implementation of

IExecutionStore.updateExecutionStatus

---

updateFailureInfo()

updateFailureInfo(executionId, failureCount, reason): Promise<boolean>

Defined in: packages/fireflow-executor/server/stores/postgres/postgres-execution-store.ts:729

Update failure count and reason for an execution

Parameters

executionId

string

failureCount

number

reason

string

Returns

Promise<boolean>

Implementation of

IExecutionStore.updateFailureInfo