Add package-owned workflow store schemas

Author: tannerlinsley

docs/api/host-adapters.md

@@ -167,6 +167,11 @@ export const config = {
 }
 ```
 
+The Netlify adapter only wakes the runtime. Apply the store adapter's
+package-owned migration during deploy/setup; do not define Workflow's
+`workflow_*` tables in application schema files unless you are intentionally
+building typed admin access.
+
 ## Vercel
 
 Install:
@@ -217,6 +222,10 @@ Configure Vercel Cron directly in `vercel.json`:
 }
 ```
 
+The Vercel adapter only wakes the runtime. Apply the store adapter's
+package-owned migration during deploy/setup; route code owns host config, while
+Workflow owns the runtime persistence schema.
+
 ## Response shape
 
 Successful adapters return:

docs/api/store-adapters.md

@@ -43,8 +43,12 @@ import { createDrizzlePostgresWorkflowStore } from '@tanstack/workflow-store-dri
 
 const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }))
 const store = createDrizzlePostgresWorkflowStore({ db })
+```
 
-await store.ensureSchema()
+Apply the package-owned migration during setup/deploy:
+
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
 ```
 
 Use it in the runtime:
@@ -76,6 +80,74 @@ Options:
 | `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.
+
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
+```
+
+Programmatic setup can use the exported migration helpers:
+
+```ts
+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:
+
+```bash
+pnpm add @tanstack/workflow-store-cloudflare-d1
+```
+
+Create the store from a D1 binding:
+
+```ts
+import { createCloudflareD1WorkflowStore } from '@tanstack/workflow-store-cloudflare-d1'
+
+const store = createCloudflareD1WorkflowStore({
+  db: env.WORKFLOW_DB,
+})
+```
+
+Apply the package-owned D1 migration during setup/deploy:
+
+```txt
+node_modules/@tanstack/workflow-store-cloudflare-d1/migrations/0000_workflow_store.sql
+```
+
+Programmatic setup can use the exported migration helpers:
+
+```ts
+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.
@@ -84,17 +156,17 @@ Creates the required tables and indexes if they do not exist.
 await store.ensureSchema()
 ```
 
-Use this from an explicit app-owned bootstrap/admin script, not from every
-request or sweep. Runtime and host adapters assume the schema exists. In
-production, you may want to run equivalent SQL through your migration system
-instead of calling this at application startup.
+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` |
@@ -104,6 +176,23 @@ instead of calling this at application startup.
 | `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:
+
+```ts
+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:

docs/cookbook/index.md

@@ -95,27 +95,33 @@ export const workflowRuntime = defineWorkflowRuntime({
 })
 ```
 
-## Create workflow tables
+## Apply workflow store migrations
 
-Use an app-owned bootstrap script for schema setup. Do not create tables from a
-host sweep handler.
+Workflow owns its durable store schema. Apply the package-owned SQL migration
+during setup/deploy instead of copying `workflow_*` tables into your app's
+Drizzle schema.
 
-```ts
-// scripts/workflow-ensure-schema.ts
-import { workflowStore } from '../src/workflows/store.server'
-
-await workflowStore.ensureSchema()
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
 ```
 
+If your deploy system wants a package script:
+
 ```json
 {
   "scripts": {
-    "workflow:ensure-schema": "tsx scripts/workflow-ensure-schema.ts"
+    "workflow:migrate": "psql \"$DATABASE_URL\" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql"
   }
 }
 ```
 
-Run this against the same `DATABASE_URL` your deployed functions use.
+Run this against the same `DATABASE_URL` your deployed functions use. Keep
+`store.ensureSchema()` for tests, local demos, and explicit admin bootstrap
+scripts.
+
+The migration records itself in `workflow_schema_migrations`. Future Workflow
+store schema changes will ship as additional numbered SQL files in the adapter
+package.
 
 ## Start a run from HTTP
 

docs/guide/deployment.md

@@ -62,29 +62,39 @@ not create tables during a cron tick, scheduled function, or worker alarm. That
 keeps production behavior explicit: migrations and bootstrap steps belong to the
 app deploy/admin process, not the background sweep path.
 
-For the Drizzle/Postgres adapter, create an app-owned script:
+For the Drizzle/Postgres adapter, Workflow owns the `workflow_*` schema. Apply
+the package-owned migration against the same database your deployed functions
+use:
 
-```ts
-// scripts/workflow-ensure-schema.ts
-import { workflowStore } from '../src/workflows/store.server'
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
+```
 
-await workflowStore.ensureSchema()
+For Cloudflare D1, use the D1-compatible package-owned migration artifact:
+
+```txt
+node_modules/@tanstack/workflow-store-cloudflare-d1/migrations/0000_workflow_store.sql
 ```
 
-Wire it into your app scripts:
+Wire it into your app scripts if your deploy provider runs package scripts:
 
 ```json
 {
   "scripts": {
-    "workflow:ensure-schema": "tsx scripts/workflow-ensure-schema.ts",
+    "workflow:migrate": "psql \"$DATABASE_URL\" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql",
     "workflow:sweep": "tsx scripts/workflow-sweep.ts"
   }
 }
 ```
 
-Run `pnpm workflow:ensure-schema` against the same `DATABASE_URL` your deployed
-functions use. In production, you can also apply equivalent SQL through your
-normal migration system.
+Do not copy Workflow's internal table declarations into your app Drizzle schema.
+Keep app code focused on workflow definitions and host entrypoints. Keep
+`store.ensureSchema()` for tests, local demos, and explicit admin bootstrap
+scripts.
+
+The migration creates `workflow_schema_migrations` so future store schema changes
+can be tracked as package-owned numbered migrations. Apply new store migrations
+before rolling out a store adapter version that expects them.
 
 ## Cloudflare
 
@@ -229,6 +239,8 @@ event arrays.
   "Run now" action to test the path before publishing.
 - Use a durable external store such as Postgres, Netlify Database, Neon, or
   another store adapter.
+- Apply the store adapter's package-owned migration during deploy/setup. The
+  scheduled function should only own host config and the sweep handler.
 - Keep `maxDurationMs` below the function timeout.
 
 ## Vercel
@@ -288,6 +300,8 @@ The adapter validates that header when you pass `cronSecret`.
   sweeps, use a plan that supports the cadence or call the sweep through another
   scheduler.
 - Use a durable external store such as Postgres. Function memory is not a store.
+- Apply the store adapter's package-owned migration during deploy/setup. The
+  route should only own host config and the sweep handler.
 
 ## Choosing a sweep cadence
 

docs/guide/index.md

@@ -31,10 +31,11 @@ This guide walks through the production shape:
 | `@tanstack/workflow-core` | The replay engine, workflow builder, primitives, middleware, version routing, and low-level `RunStore`. |
 | `@tanstack/workflow-runtime` | The deployment-independent runtime, execution store contract, schedules, timers, leases, and sweep driver. |
 | `@tanstack/workflow-store-drizzle-postgres` | A Postgres implementation of the runtime execution store contract using Drizzle as the SQL surface. |
-| `@tanstack/workflow-cloudflare` | A Cloudflare Worker `scheduled()` handler and Wrangler cron config helper that call `runtime.sweep()`. |
+| `@tanstack/workflow-store-cloudflare-d1` | A Cloudflare D1 implementation of the runtime execution store contract. |
+| `@tanstack/workflow-cloudflare` | A Cloudflare Worker `scheduled()` handler that calls `runtime.sweep()`. |
 | `@tanstack/workflow-railway` | A Railway Cron Job command helper that calls `runtime.sweep()` and exits. |
-| `@tanstack/workflow-netlify` | A Netlify Scheduled Function handler and config helper that call `runtime.sweep()`. |
-| `@tanstack/workflow-vercel` | A Vercel route handler and cron config helper that call `runtime.sweep()`. |
+| `@tanstack/workflow-netlify` | A Netlify Scheduled Function handler that calls `runtime.sweep()`. |
+| `@tanstack/workflow-vercel` | A Vercel route handler that calls `runtime.sweep()`. |
 
 The important boundary is this:
 
@@ -172,8 +173,13 @@ import { createDrizzlePostgresWorkflowStore } from '@tanstack/workflow-store-dri
 
 const db = drizzle(new Pool({ connectionString: process.env.DATABASE_URL }))
 const store = createDrizzlePostgresWorkflowStore({ db })
+```
+
+Apply the package-owned Workflow store migration before runtime sweeps or
+requests hit that database:
 
-await store.ensureSchema()
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
 ```
 
 Then pass `store` to `defineWorkflowRuntime`. The runtime will use it for:
@@ -340,6 +346,8 @@ export const config = {
 ```
 
 The Scheduled Function only wakes the runtime. It does not store workflow state.
+Apply the package-owned store migration during deploy/setup; do not mirror
+Workflow's `workflow_*` tables in app schema files.
 
 ## Deploy on Vercel
 
@@ -375,6 +383,9 @@ Configure Vercel Cron:
 ```
 
 The Vercel Cron Job wakes the route. The database decides what is actually due.
+Apply the package-owned store migration during deploy/setup; app code owns the
+workflow definitions and route config, while Workflow owns its persistence
+schema.
 
 ## Why this works on serverless hosts
 

docs/guide/persistence.md

@@ -165,14 +165,22 @@ const store = createDrizzlePostgresWorkflowStore({
   db,
   schema: 'public',
 })
+```
+
+Apply the package-owned migration during setup/deploy:
 
-await store.ensureSchema()
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
 ```
 
-`ensureSchema()` is useful for local demos, tests, and explicit bootstrap
-scripts. Runtime sweeps and host adapters do not call it for you. A missing table
-during `runtime.sweep()` means the deployed database has not been migrated yet,
-not that the host adapter failed.
+Workflow owns the `workflow_*` table definitions, indexes, leases, timers,
+schedules, and compatibility expectations. Apps should not copy those tables
+into their own Drizzle schema for normal runtime use.
+
+`ensureSchema()` is still useful for local demos, tests, and explicit admin
+bootstrap scripts. Runtime sweeps and host adapters do not call it for you. A
+missing table during `runtime.sweep()` means the deployed database has not been
+migrated yet, not that the host adapter failed.
 
 You can override table names:
 
@@ -189,6 +197,16 @@ const store = createDrizzlePostgresWorkflowStore({
 The default tables include runs, run states, event locks, events, timers, signal
 deliveries, schedules, and schedule buckets.
 
+Future schema changes are versioned with
+`@tanstack/workflow-store-drizzle-postgres`. Apply new package migrations as part
+of upgrading the store package. The runtime assumes the database schema is
+compatible with the installed store adapter version.
+
+The first migration also creates `workflow_schema_migrations` and records the
+applied migration ID. Future store migrations will be published as additional
+numbered SQL files and should be applied in order before the new adapter version
+handles production traffic.
+
 ## Retention
 
 Terminal runs usually remain for some period so:

docs/installation.md

@@ -44,9 +44,30 @@ pnpm add @tanstack/workflow-store-drizzle-postgres drizzle-orm pg
 import { createDrizzlePostgresWorkflowStore } from '@tanstack/workflow-store-drizzle-postgres'
 
 const store = createDrizzlePostgresWorkflowStore({ db })
-await store.ensureSchema()
 ```
 
+Apply the package-owned store migration during setup/deploy:
+
+```bash
+psql "$DATABASE_URL" -f node_modules/@tanstack/workflow-store-drizzle-postgres/migrations/0000_workflow_store.sql
+```
+
+For Cloudflare D1:
+
+```bash
+pnpm add @tanstack/workflow-store-cloudflare-d1
+```
+
+```ts
+import { createCloudflareD1WorkflowStore } from '@tanstack/workflow-store-cloudflare-d1'
+
+const store = createCloudflareD1WorkflowStore({ db: env.WORKFLOW_DB })
+```
+
+Copy or reference the package-owned SQL artifact from
+`node_modules/@tanstack/workflow-store-cloudflare-d1/migrations/0000_workflow_store.sql`
+in your D1 migration flow.
+
 ## Server framework
 
 Engine is framework-agnostic. Two entry points: