docs: SQLite to Postgres cutover runbook (#25)
Proves the import against a copy of the real library before the real one is at risk, and writes the procedure down so it can be repeated at cutover against a fresh export. Verified on 2026-08-08: a throwaway generator read a copy of bookmarks-20260807-213515.db and emitted Series-then-Bookmarks SQL against a scratch Postgres whose schema and owner Reader were built by the real binary. Result: 29 Bookmarks (18 reading, 11 archived, 7 favourites), 29 Series matching the distinct (site, series_id) count, every Bookmark owned by the seeded Reader, and a field-by-field diff of all 29 rows against the source showing zero differences. GET /bookmarks over the real read path returned the same 29. Production was not touched. The generator itself stays out of the repository: its output is the owner's reading history, and it reads SQLite, which the backend module dropped in ADR-0001. CUTOVER.md specifies the transformation instead of shipping a script.
This commit is contained in:
+4
-3
@@ -160,8 +160,8 @@ ls -1t "$BACKUP_DIR"/bookmarks-*.dump | tail -n +31 | xargs -r rm -v
|
||||
`bookmarks-data` is the **pre-migration SQLite volume**. It is deliberately not
|
||||
declared in `docker-compose.yml` any more, which is what keeps `docker compose
|
||||
down -v` from taking it with the rest of the stack. It is not the live database
|
||||
and nothing reads it. Once the Postgres data has been trusted for a while,
|
||||
remove it by hand — nothing else will:
|
||||
and nothing reads it — the one-way move out of it is `CUTOVER.md`. Once the
|
||||
Postgres data has been trusted for a while, remove it by hand — nothing else will:
|
||||
|
||||
```bash
|
||||
docker volume rm bookmarkmanager_bookmarks-data
|
||||
@@ -396,5 +396,6 @@ panel works on the phone.
|
||||
| `pg_restore`: `cannot drop … other objects depend on it` / `being accessed by other users` | Live connections block `--clean`. `$COMPOSE stop bookmark-api` first (§6). If they persist: `$COMPOSE exec -T postgres psql -U bookmarks -d postgres -c "select pg_terminate_backend(pid) from pg_stat_activity where datname='bookmarks' and pid <> pg_backend_pid()"`. |
|
||||
| Dump is 0 bytes, or `pg_restore`: `did not find magic string in file header` | You ran `exec` without `-T`. The allocated TTY rewrites newlines in the binary stream and corrupts the archive in flight (§1). |
|
||||
|
||||
Full first-time setup: `DEPLOY.md`. Config reference and endpoints: `README.md`.
|
||||
Full first-time setup: `DEPLOY.md`. The one-off SQLite→Postgres move:
|
||||
`CUTOVER.md`. Config reference and endpoints: `README.md`.
|
||||
UI conventions: `docs/design-system.md`.
|
||||
|
||||
Reference in New Issue
Block a user