| 1 | # SQLite fixtures |
| 2 | |
| 3 | Load this reference only when inspecting or seeding local T3 state directly. |
| 4 | |
| 5 | ## Select the correct database |
| 6 | |
| 7 | When `--base-dir` or `--home-dir` is explicit, runtime state lives under `<base-dir>/userdata` and the database path is `<base-dir>/userdata/statev2.sqlite`. The `<base-dir>/dev` state directory is only the fallback for an implicit development home, preventing an ordinary `vp run dev` from touching production state. |
| 8 | |
| 9 | The server copies the V1 `state.sqlite` into `statev2.sqlite` only when `statev2.sqlite` is missing. After the first start, edits to `state.sqlite` change nothing. |
| 10 | |
| 11 | Start the target runtime once before seeding so all migrations have run. Use an isolated base directory. Stop the server before writes to avoid racing application state or an active projection. |
| 12 | |
| 13 | ## Use the helper |
| 14 | |
| 15 | List tables: |
| 16 | |
| 17 | ```bash |
| 18 | node apps/server/scripts/t3-sqlite-state.ts query \ |
| 19 | --base-dir <base-dir> \ |
| 20 | --sql "SELECT name FROM sqlite_schema WHERE type = 'table' ORDER BY name" |
| 21 | ``` |
| 22 | |
| 23 | Inspect current columns before writing a fixture: |
| 24 | |
| 25 | ```bash |
| 26 | node apps/server/scripts/t3-sqlite-state.ts query \ |
| 27 | --base-dir <base-dir> \ |
| 28 | --sql "PRAGMA table_info(orchestration_v2_projection_threads)" |
| 29 | ``` |
| 30 | |
| 31 | Apply a SQL fixture from a file: |
| 32 | |
| 33 | ```bash |
| 34 | node apps/server/scripts/t3-sqlite-state.ts exec \ |
| 35 | --base-dir <base-dir> \ |
| 36 | --file /tmp/t3-seed.sql |
| 37 | ``` |
| 38 | |
| 39 | Use one statement per invocation for both `query` and `exec`; the helper wraps writes in a transaction and prints the backup path after a successful mutation. Use a single insert with multiple value rows when a fixture needs several records. |
| 40 | |
| 41 | ## Seed projection data carefully |
| 42 | |
| 43 | Clients read projects from `projection_projects` and everything else from the `orchestration_v2_projection_*` tables: threads, runs, messages, turn items, runtime requests, plans, and provider sessions. The older `projection_thread*` tables hold V1 history, which the server imports once per thread at startup; later edits there do not reach the UI. |
| 44 | |
| 45 | Most V2 rows carry a `payload_json` that must decode against the schemas in `packages/contracts/src/orchestrationV2.ts`. The safest start is a row the app wrote itself: create a thread through the UI, copy its rows, and edit them. Keep identifiers unique, timestamps as ISO strings, and related project, thread, and run IDs consistent. |
| 46 | |
| 47 | Direct projection writes are appropriate for ephemeral visual states, edge-case counts, long titles, long timelines, and similar UI fixtures. They do not create a coherent event history. Leave the event log (`orchestration_events`) unchanged, and do not use direct projection writes to claim backend business behavior works. |
| 48 | |
| 49 | Use the app's commands or APIs for behavior tests. Use `node apps/server/src/bin.ts auth ...` for auth state rather than editing `auth_pairing_links` or `auth_sessions`. |