feat(persistence): add SQL migration CLI docs

Author: AlemTuzlak

docs/config.json

@@ -407,7 +407,7 @@
           "label": "Overview",
           "to": "persistence/overview",
           "addedAt": "2026-06-18",
-          "updatedAt": "2026-07-07"
+          "updatedAt": "2026-07-08"
         },
         {
           "label": "Resumable Chat",
@@ -449,7 +449,7 @@
           "label": "Custom Stores",
           "to": "persistence/custom-stores",
           "addedAt": "2026-07-03",
-          "updatedAt": "2026-07-06"
+          "updatedAt": "2026-07-08"
         },
         {
           "label": "Sandbox Runs",

docs/persistence/cloudflare.md

@@ -33,6 +33,12 @@ export function persistence(env: Env) {
 `d1` is required. `r2` and `durableObjects` are optional; include them only when
 your app needs blob/artifact storage or distributed locks.
 
+You can also use R2 as the blob side of a hybrid persistence design while your
+app keeps runs, messages, events, metadata, and artifact indexes in a separate
+user-owned database. Implement that shape with [Custom Stores](./custom-stores):
+the Cloudflare backend is convenient when D1 owns the SQL state, but the R2
+artifact/blob pattern is not limited to D1.
+
 For the end-to-end file persistence model, including generated artifacts,
 app-owned blobs, and sandbox workspace checkpoints backed by R2, see
 [Files and Artifacts](./files-and-artifacts).

docs/persistence/custom-stores.md

@@ -12,6 +12,13 @@ a packaged backend, start with [SQL Backends](./sql-backends) or
 [Cloudflare](./cloudflare). If you need the end-to-end chat journey, start with
 [Resumable Chat](./resumable-chat).
 
+For production apps, this is the recommended ownership model: keep persistence
+inside your app's database, queue, object store, and retention policies, then
+expose those systems to TanStack AI through `AIPersistence` store callback
+methods. The packaged SQL and Cloudflare backends are TanStack primitives you
+can opt into when they match your stack, but the store contract is the stable
+boundary for user-owned persistence.
+
 If you are deciding how to model generated files, workspace checkpoints, object
 bytes, metadata manifests, and locks together, read
 [Files and Artifacts](./files-and-artifacts) first. This page explains the store
@@ -65,6 +72,69 @@ const middleware = withPersistence(persistence, {
 
 If any required store is missing, setup fails before the run starts.
 
+`defineAIPersistence(...)` is only an identity helper for the aggregate store
+object. There is no separate high-level callback builder: implement the store
+methods directly and pass them under `stores`.
+
+## Use your existing persistence boundary
+
+Most production apps already have repositories or service methods for threads,
+runs, event logs, user decisions, metadata, and files. Wrap those methods in the
+store callbacks instead of adding a second persistence path.
+
+```ts group=custom-stores
+import {
+  defineAIPersistence,
+  withPersistence,
+} from '@tanstack/ai-persistence'
+import type { MessageStore, RunStore } from '@tanstack/ai-persistence'
+import type { ModelMessage } from '@tanstack/ai'
+
+type AppDb = {
+  threads: {
+    loadMessages: (threadId: string) => Promise<Array<ModelMessage>>
+    replaceMessages: (
+      threadId: string,
+      messages: Array<ModelMessage>,
+    ) => Promise<void>
+  }
+  runs: {
+    createOrResume: RunStore['createOrResume']
+    update: RunStore['update']
+    get: RunStore['get']
+  }
+}
+
+function appMessageStore(db: AppDb): MessageStore {
+  return {
+    loadThread: (threadId) => db.threads.loadMessages(threadId),
+    saveThread: (threadId, messages) =>
+      db.threads.replaceMessages(threadId, messages),
+  }
+}
+
+export function appPersistence(db: AppDb) {
+  return defineAIPersistence({
+    stores: {
+      messages: appMessageStore(db),
+      runs: db.runs,
+    },
+  })
+}
+
+export function persistenceMiddleware(db: AppDb) {
+  return withPersistence(appPersistence(db), {
+    features: ['messages'],
+  })
+}
+```
+
+Add `publicEvents` when reconnect replay matters, `interrupts` when runs pause
+for user action, `internalEvents` for package or workflow checkpoints,
+`metadata` for app-owned correlation, `locks` for cross-process coordination,
+and `artifacts` plus `blobs` when runs produce durable files or media. Every
+persistence feature is supported by implementing the corresponding stores.
+
 | Feature | Required stores |
 | --- | --- |
 | `messages` | `stores.messages` |
@@ -118,6 +188,12 @@ object storage, as the [Cloudflare backend](./cloudflare) does with D1 and R2.
 For concrete run-artifact, blob, and sandbox workspace examples, see
 [Files and Artifacts](./files-and-artifacts).
 
+The same hybrid pattern works outside Workers: use your SQL database for runs,
+messages, events, metadata, and artifact indexes, then implement `stores.blobs`
+against R2 or another object store for large bytes. Keep the blob key or
+artifact id in your SQL-owned records so your app, not TanStack AI, controls
+garbage collection, access checks, and retention.
+
 ## Extend without growing the base schema
 
 MCP and workflow packages should build on the common stores instead of adding

docs/persistence/files-and-artifacts.md

@@ -21,6 +21,12 @@ If you pass a manual `features` list to `withPersistence(...)`, include
 scenarios. Manual feature lists must pair `'artifacts'` with `'blobs'` because
 artifact metadata and stored bytes are enabled together.
 
+The backend can be hybrid. A common production shape is a user-owned SQL
+database for runs, messages, events, metadata, and artifact indexes, plus R2 or
+another object store for large bytes behind `stores.blobs`. Use
+[Custom Stores](./custom-stores) when your app needs that split instead of a
+packaged backend.
+
 For resumable image, audio, speech, transcription, and video hooks, start with
 [Resumable Generations](./resumable-generations). This page focuses on the
 artifact and blob records those endpoints create.

docs/persistence/overview.md

@@ -11,6 +11,36 @@ storage primitives with sandbox and workflow extensions.
 Persistence is optional middleware. A run with no persistence middleware behaves
 exactly as before.
 
+## Control ladder
+
+Persistence has several control levers. Start at the lowest rung that gives
+your app the durability it needs, then opt into more stores only when a feature
+requires them.
+
+| Lever | You control | TanStack AI provides | Use it when |
+| --- | --- | --- | --- |
+| No persistence | Nothing | Normal in-memory run behavior | A run can disappear after the request ends. |
+| Client resume snapshot | Where the client stores `{ threadId, runId, cursor }` | `persistence.server`, `autoResume`, and `resume()` in the client hooks | A page refresh should reconnect to a still-durable server run. |
+| Messages | `stores.messages.loadThread` and `saveThread` | Server-authoritative thread history loading/saving | The server owns the transcript instead of trusting the browser. |
+| Durable replay | `stores.runs` and `stores.publicEvents` | Opaque cursors, run records, AG-UI event append, and replay | Reconnects must continue a run without calling the model again. |
+| Interrupts | `stores.interrupts` plus replay stores | Durable pending human decisions and resume payload handling | A run can pause for approval, input, or another user action. |
+| Internal checkpoints | `stores.internalEvents` | A separate non-UI event log | Packages or app workflows need checkpoints that should not replay to users. |
+| Metadata | `stores.metadata` | Namespaced key/value access | Your app needs durable correlation, manifests, or integration state. |
+| Locks | `stores.locks` | Shared lock capability consumed by integrations | Multiple workers can resume or mutate the same durable resource. |
+| Artifacts and blobs | `stores.artifacts` and `stores.blobs` | Durable artifact refs for generated files and media | Runs create downloadable files, media, or workspace checkpoints. |
+| SQL or platform backend | Database schema, migration timing, deployment topology | Backend factories that implement the same stores | You want TanStack primitives on top of your chosen database or platform. |
+
+For production, prefer user-owned persistence through an `AIPersistence` object
+created with `defineAIPersistence(...)` or a backend factory that returns the
+same store contract. TanStack AI should call your existing storage boundary
+through store callback methods; it should not be the part of your production
+system that silently owns raw SQL schema lifecycle or data-retention policy.
+
+Packaged backends such as SQLite, Postgres, Prisma, Drizzle, and Cloudflare are
+useful primitives when they fit your stack. They still expose the same
+`AIPersistence` stores, so you can start with a backend package, replace one
+store at a time, or compose SQL metadata with object storage for artifacts.
+
 ## What persistence stores
 
 `withPersistence(...)` can:

docs/persistence/sql-backends.md

@@ -9,10 +9,17 @@ clients all expose the same `AIPersistence` stores to `withPersistence(...)`.
 The shared SQL core includes a MySQL dialect for adapter authors, but the
 published raw backend packages are SQLite and Postgres.
 
+For production, treat the SQL schema as part of your app-owned persistence
+boundary. Generate or copy the TanStack AI DDL into your normal migration
+system, review it like any other schema change, and deploy it before traffic
+uses the persistence stores. Use lazy migration only when you intentionally want
+the backend to create tables at runtime.
+
 ## Raw SQL backends
 
 SQLite is file-backed and works well for local apps, prototypes, and single-node
-deployments.
+deployments. Fresh development examples can set `migrate: true` explicitly so a
+new local database creates its tables on first use.
 
 ```ts
 import { sqlitePersistence } from '@tanstack/ai-persistence-sqlite'
@@ -35,8 +42,8 @@ export const persistence = postgresPersistence({
 ```
 
 Both raw backends use the shared SQL core. They do not create persistence
-tables by default; set `migrate: true` to opt in to lazy table creation on
-first use.
+tables by default. `migrate` is `false` unless you pass `migrate: true`, which
+opts into lazy table creation on first use.
 
 ## Shared schema
 
@@ -72,6 +79,33 @@ export const migrationStatements = ddl('postgres')
 Apply those statements with your normal migration system before traffic reaches
 the app.
 
+## Generate SQL migrations
+
+Use the generic SQL CLI when you want a migration file without importing DDL in
+application code. It emits the shared SQL persistence schema for every SQL
+dialect supported by the core generator: SQLite, Postgres, and MySQL.
+
+```sh
+pnpm exec tanstack-ai-persistence-sql --dialect sqlite --out migrations/001_tanstack_ai.sql
+pnpm exec tanstack-ai-persistence-sql --dialect postgres --stdout
+pnpm exec tanstack-ai-persistence-sql --dialect mysql --out migrations/001_tanstack_ai.sql
+```
+
+Options:
+
+| Option | Purpose |
+| --- | --- |
+| `--dialect sqlite\|postgres\|mysql` | Choose the SQL dialect to generate. |
+| `--out <path>` | Write SQL to a migration file. |
+| `--stdout` | Print SQL instead of writing a file. |
+| `--timestamp <yyyymmddhhmmss>` | Use a deterministic timestamp in generated default names. |
+| `--name <name>` | Use a deterministic migration name. |
+| `--force` | Overwrite an existing output file. |
+
+The generic CLI writes only the shared SQL persistence schema. Cloudflare R2
+artifact indexes, ORM-specific migration folder layouts, and app-owned tables
+remain separate.
+
 ## Drizzle and Prisma
 
 Use the ORM-backed packages when your app already owns its database client and
@@ -100,6 +134,10 @@ pnpm exec tanstack-ai-persistence-prisma --dialect postgres
 pnpm exec tanstack-ai-persistence-drizzle --dialect postgres
 ```
 
+Use the ORM-specific CLIs when you want their default migration layout. Use the
+generic `tanstack-ai-persistence-sql` CLI when you only want SQL text or when
+you are generating MySQL DDL for a custom adapter.
+
 The default Prisma path is
 `prisma/migrations/<timestamp>_tanstack_ai_persistence/migration.sql`. The
 default Drizzle path is `drizzle/<timestamp>_tanstack_ai_persistence.sql`.
@@ -144,6 +182,12 @@ import { ddl } from '@tanstack/ai-persistence-sql'
 export const migrationStatements = ddl('mysql')
 ```
 
+You can also generate the same MySQL DDL with the generic CLI:
+
+```sh
+pnpm exec tanstack-ai-persistence-sql --dialect mysql --out migrations/tanstack_ai.sql
+```
+
 ## Choosing a backend
 
 Use SQLite when one process owns the database file. Use Postgres when multiple