feat: SQLite persistence core

.changeset/sqlite-persistence.md

@@ -0,0 +1,27 @@
+---
+'@tanstack/db': patch
+'@tanstack/db-sqlite-persisted-collection-core': patch
+'@tanstack/db-browser-wa-sqlite-persisted-collection': patch
+'@tanstack/db-react-native-sqlite-persisted-collection': patch
+---
+
+feat(persistence): add SQLite-based offline persistence for collections
+
+Adds a new persistence layer that durably stores collection data in SQLite, enabling applications to survive page reloads and app restarts.
+
+**Core persistence (`@tanstack/db-sqlite-persisted-collection-core`)**
+
+- New package providing the shared SQLite persistence runtime: hydration, streaming, transaction tracking, and applied-tx pruning
+- SQLite core adapter with full query compilation, index management, and schema migration support
+- Portable conformance test contracts for runtime-specific adapters
+
+**Browser (`@tanstack/db-browser-wa-sqlite-persisted-collection`)**
+
+- New package for browser persistence via wa-sqlite backed by OPFS
+- Single-tab persistence with OPFS-based SQLite storage
+- `BrowserCollectionCoordinator` for multi-tab leader-election and cross-tab sync
+
+**React Native (`@tanstack/db-react-native-sqlite-persisted-collection`)**
+
+- New package for React Native persistence via op-sqlite
+- Adapter with transaction deadlock prevention and runtime parity coverage

.github/workflows/e2e-tests.yml

@@ -9,7 +9,7 @@ jobs:
   e2e-tests:
     name: Run E2E Tests
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 35
 
     steps:
       - name: Checkout code
@@ -62,6 +62,43 @@ jobs:
         env:
           ELECTRIC_URL: http://localhost:3000
 
+      - name: Run React Native/Expo persisted collection E2E tests
+        run: |
+          cd packages/db-react-native-sqlite-persisted-collection
+          pnpm test:e2e
+
+      - name: Run React Native/Expo runtime E2E lane
+        run: |
+          is_fork_pr=false
+          require_runtime_lane=${TANSTACK_DB_REQUIRE_MOBILE_RUNTIME_LANE:-0}
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request" ]; then
+            is_fork_pr=$(jq -r '.pull_request.head.repo.fork' "${GITHUB_EVENT_PATH}")
+          fi
+
+          if [ "${is_fork_pr}" = "true" ]; then
+            echo "Skipping runtime mobile lane for fork PR (repo vars are unavailable)."
+            exit 0
+          fi
+
+          if [ -z "${TANSTACK_DB_MOBILE_SQLITE_FACTORY_MODULE}" ]; then
+            if [ "${require_runtime_lane}" = "1" ]; then
+              echo "::error::Missing repository variable TANSTACK_DB_MOBILE_SQLITE_FACTORY_MODULE while TANSTACK_DB_REQUIRE_MOBILE_RUNTIME_LANE=1."
+              echo "::error::Set TANSTACK_DB_MOBILE_SQLITE_FACTORY_MODULE (and optional TANSTACK_DB_MOBILE_SQLITE_FACTORY_EXPORT)."
+              exit 1
+            fi
+
+            echo "Skipping runtime mobile lane (no TANSTACK_DB_MOBILE_SQLITE_FACTORY_MODULE configured)."
+            echo "Set TANSTACK_DB_REQUIRE_MOBILE_RUNTIME_LANE=1 to enforce this lane."
+            exit 0
+          fi
+
+          cd packages/db-react-native-sqlite-persisted-collection
+          pnpm test:e2e:runtime
+        env:
+          TANSTACK_DB_MOBILE_SQLITE_FACTORY_MODULE: ${{ vars.TANSTACK_DB_MOBILE_SQLITE_FACTORY_MODULE }}
+          TANSTACK_DB_MOBILE_SQLITE_FACTORY_EXPORT: ${{ vars.TANSTACK_DB_MOBILE_SQLITE_FACTORY_EXPORT }}
+          TANSTACK_DB_REQUIRE_MOBILE_RUNTIME_LANE: ${{ vars.TANSTACK_DB_REQUIRE_MOBILE_RUNTIME_LANE }}
+
       - name: Stop Docker services
         if: always()
         run: |

package.json

@@ -10,7 +10,11 @@
   "pnpm": {
     "overrides": {
       "metro": "0.82.5"
-    }
+    },
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "electron"
+    ]
   },
   "scripts": {
     "build": "pnpm --filter \"./packages/**\" build",

packages/db-browser-wa-sqlite-persisted-collection/README.md

@@ -0,0 +1,54 @@
+# @tanstack/db-browser-wa-sqlite-persisted-collection
+
+Thin browser SQLite persistence for TanStack DB using `wa-sqlite` + OPFS.
+
+## Public API
+
+- `createBrowserWASQLitePersistence(...)`
+- `openBrowserWASQLiteOPFSDatabase(...)`
+- `persistedCollectionOptions(...)` (re-exported from core)
+
+## Quick start
+
+```ts
+import { createCollection } from '@tanstack/db'
+import {
+  createBrowserWASQLitePersistence,
+  openBrowserWASQLiteOPFSDatabase,
+  persistedCollectionOptions,
+} from '@tanstack/db-browser-wa-sqlite-persisted-collection'
+
+type Todo = {
+  id: string
+  title: string
+  completed: boolean
+}
+
+const database = await openBrowserWASQLiteOPFSDatabase({
+  databaseName: `tanstack-db.sqlite`,
+})
+
+const persistence = createBrowserWASQLitePersistence({
+  database,
+})
+
+export const todosCollection = createCollection(
+  persistedCollectionOptions<Todo, string>({
+    id: `todos`,
+    getKey: (todo) => todo.id,
+    persistence,
+    schemaVersion: 1, // Per-collection schema version
+  }),
+)
+```
+
+## Notes
+
+- This package is Phase 7 single-tab browser wiring: it uses
+  `SingleProcessCoordinator` semantics by default.
+- `openBrowserWASQLiteOPFSDatabase(...)` starts a dedicated Web Worker and
+  routes SQL operations through it. OPFS sync access handle APIs are used in
+  that worker context.
+- Single-tab mode does not require BroadcastChannel or Web Locks for
+  correctness.
+- OPFS capability failures are surfaced as `PersistenceUnavailableError`.