Keep startup database rebuilds out of memory

2026-10-06 15:18:13 -04:00
parent 8f8897b86b
commit 6999a33aef
12 changed files with 184 additions and 15 deletions
@@ -198,6 +198,15 @@ after database changes, capture these timings under the same fleet load and run
 the largest tables/indexes, database and WAL sizes, and free pages. This command
 opens an existing database read-only and does not run app migrations.
 The controller uses a 128 MiB page cache and each reader worker uses 32 MiB.
+Main-database migrations use a 16 MiB cache with memory mapping disabled; SQLite
+temporary storage stays disk-backed during migrations and normal operation.
+The container uses `/data/.sqlite-tmp` for SQLite scratch files so a memory-backed
+`/tmp` cannot turn a database rebuild into an allocation of the whole database.
+Override `SQLITE_TMPDIR` only with another writable, disk-backed directory.
+Startup logs identify migration phases, elapsed time and resident memory. A
+completed migration is retained across restarts; SQLite rolls back interrupted
+transactions and startup retries those migrations. The one-time vacuum still needs disk space for its temporary
+copy. Do not remove `cherry.db-wal` to recover from an interrupted upgrade.
 For a local data disk, set `EC_SQLITE_MMAP_MB=256` to enable memory-mapped reads.
 Query statistics are optimized at startup and hourly; WAL reuse is capped at
 64 MiB after checkpoints (active transactions can temporarily grow it larger).