Skip to content

store-adapters.md

Latest commit

 

History

History
220 lines (162 loc) · 5.84 KB

store-adapters.md

File metadata and controls

220 lines (162 loc) · 5.84 KB
id store-adapters
title Store Adapters

Store adapters

Store adapters implement WorkflowExecutionStore from @tanstack/workflow-runtime.

WorkflowExecutionStore

The runtime store contract includes:

Capability Methods
Run lifecycle createRun, loadRun, loadExecution, markRunPaused, markRunFinished, markRunErrored
Event log appendEvents, readEvents, optional subscribeEvents
Leases claimRun, heartbeatRunLease, releaseRunLease, claimStaleRuns
Timers scheduleTimer, claimDueTimers
Signals deliverSignal
Approvals deliverApproval
Schedules upsertSchedule, claimDueScheduleBuckets, markScheduleBucketStarted
Query listRuns, getRunTimeline

Adapter authors should run the shared contract tests from @tanstack/workflow-runtime.

Drizzle/Postgres

Install:

pnpm add @tanstack/workflow-store-drizzle-postgres drizzle-orm pg

Create the store:

import { drizzle } from 'drizzle-orm/node-postgres'
import { Pool } from 'pg'
import { createDrizzlePostgresWorkflowStore } from '@tanstack/workflow-store-drizzle-postgres'

const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }))
const store = createDrizzlePostgresWorkflowStore({ db })

Apply the package-owned migration during setup/deploy:

psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql

Use it in the runtime:

const runtime = defineWorkflowRuntime({
  store,
  workflows,
})

createDrizzlePostgresWorkflowStore

const store = createDrizzlePostgresWorkflowStore({
  db,
  schema: 'public',
  tables: {
    runs: 'workflow_runs',
  },
})

Options:

Option Purpose
db Drizzle-compatible database object with execute and optional transaction.
schema Optional Postgres schema name.
tables Optional table name overrides.

Package-owned migrations

The Drizzle/Postgres package owns the durable Workflow schema. Apps should apply the SQL artifact from the installed package instead of mirroring workflow_* tables in application Drizzle schema files.

psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql

Programmatic setup can use the exported migration helpers:

import {
  getDrizzlePostgresWorkflowStoreMigrationSql,
  getDrizzlePostgresWorkflowStoreMigrations,
} from '@tanstack/workflow-store-drizzle-postgres'

Schema changes are versioned with @tanstack/workflow-store-drizzle-postgres. Apply new package migrations when upgrading the adapter. Runtime code assumes the database schema is compatible with the installed store adapter version.

The initial migration creates workflow_schema_migrations and records applied Workflow store migrations. Future migrations will be appended as new numbered SQL files in the package. Apply them in order during deploy/setup before running the new adapter version.

Maintainers changing the Drizzle/Postgres store schema should follow the package-local SCHEMA_MIGRATIONS.md checklist.

Cloudflare D1

Install:

pnpm add @tanstack/workflow-store-cloudflare-d1

Create the store from a D1 binding:

import { createCloudflareD1WorkflowStore } from '@tanstack/workflow-store-cloudflare-d1'

const store = createCloudflareD1WorkflowStore({
  db: env.WORKFLOW_DB,
})

Apply the package-owned D1 migration during setup/deploy:

node_modules/@tanstack/workflow-store-cloudflare-d1/migrations/0000_workflow_store.sql

Programmatic setup can use the exported migration helpers:

import {
  getCloudflareD1WorkflowStoreMigrationSql,
  getCloudflareD1WorkflowStoreMigrations,
} from '@tanstack/workflow-store-cloudflare-d1'

D1 stores JSON payloads as text and uses SQLite integer timestamps. Its claim operations use atomic conditional updates and leases rather than Postgres FOR UPDATE SKIP LOCKED.

store.ensureSchema

Creates the required tables and indexes if they do not exist.

await store.ensureSchema()

Use this from tests, local demos, or an explicit admin bootstrap script, not from every request or sweep. Runtime and host adapters assume the schema exists. Production deploys should prefer the package-owned SQL migration artifact.

Default tables

defaultDrizzlePostgresWorkflowStoreTables contains:

Table key Default table
schemaMigrations workflow_schema_migrations
runs workflow_runs
runStates workflow_run_states
eventLocks workflow_event_locks
events workflow_events
timers workflow_timers
signalDeliveries workflow_signal_deliveries
schedules workflow_schedules
scheduleBuckets workflow_schedule_buckets

Optional Drizzle table definitions

The package exports Drizzle table definitions for apps that explicitly want typed read access for dashboards, diagnostics, or admin tooling:

import {
  workflowEvents,
  workflowRuns,
  workflowSchedules,
  workflowSchemaMigrations,
} from '@tanstack/workflow-store-drizzle-postgres'

These exports are optional. Normal runtime use does not require adding Workflow tables to your app schema.

In-memory store

For tests and demos:

import { inMemoryWorkflowExecutionStore } from '@tanstack/workflow-runtime'

const store = inMemoryWorkflowExecutionStore()

The in-memory store implements the same runtime contract, but it is not durable.

Adapter implementation checklist

A production store adapter should satisfy:

  • compare-and-swap append semantics for events
  • idempotent run creation
  • idempotent signal and approval delivery
  • atomic claim and lease semantics
  • due timer and due schedule indexes
  • stale lease recovery
  • timeline and list APIs
  • migration strategy
  • tests against the shared contract suite