Environment:
- Engine: PGLite (default, embedded)
- Bun: 1.2.21
- Node: v22.22.2
- OS: Ubuntu 24.04.4 LTS (Noble Numbat)
- Brain created: ~Nov 7, 2025 (gbrain v0.26.x era)
- Schema version before upgrade attempt: 33
- Pages in DB: 26
Repro:
# Starting state: v0.26.1 brain with schema v33
gbrain --version # 0.26.1
gbrain stats # 26 pages, healthy
# Upgrade to v0.30.2
git checkout master && bun install && bun link
gbrain --version # 0.30.2
# postinstall migrations partially fail:
# v0.28.0: PARTIAL
# v0.29.1: FAILED — column "effective_date" does not exist
# Manual fix attempts also fail:
gbrain init --migrate-only # ❌ same error
gbrain apply-migrations --yes # ❌ v0.29.1 failed
# gbrain doctor:
# - Health: 55/100
# - FAIL: minions_migration (HALF-INSTALLED)
# - WARN: schema 33/44, effective_date column unavailable
Root cause:
In src/core/pglite-engine.ts, applyForwardReferenceBootstrap() (around L248) covers columns up to v0.26.5 (deleted_at) but not the 4 columns added in v0.29.1:
effective_dateeffective_date_sourceimport_filenamesalience_touched_at
The fail point is in getPGLiteSchema():
CREATE INDEX IF NOT EXISTS pages_coalesce_date_idx
ON pages ((COALESCE(effective_date, updated_at)))
This index creation fails because effective_date column doesn't exist. CREATE TABLE IF NOT EXISTS won't alter existing tables to add the column, and the bootstrap that's supposed to handle this gap doesn't include the v0.29.1 columns.
The forward reference bootstrap was introduced in v0.28.5 ("PGLite upgrade wedge fix") to handle exactly this scenario, but the bootstrap code wasn't updated when v0.29.1 added the new columns. Likely a process gap rather than a fundamental design flaw.
Impact:
PGLite brains created with gbrain ≤v0.28.x cannot upgrade to v0.30 cleanly. They get stuck in MINIONS HALF-INSTALLED state. Both init --migrate-only and apply-migrations --yes fail with the same error.
Workaround:
-- Connect to PGLite manually
ALTER TABLE pages ADD COLUMN IF NOT EXISTS effective_date TIMESTAMPTZ;
ALTER TABLE pages ADD COLUMN IF NOT EXISTS effective_date_source TEXT;
ALTER TABLE pages ADD COLUMN IF NOT EXISTS import_filename TEXT;
ALTER TABLE pages ADD COLUMN IF NOT EXISTS salience_touched_at TIMESTAMPTZ;
Then re-run gbrain init --migrate-only and gbrain apply-migrations --yes.
Suggested fix:
Update applyForwardReferenceBootstrap() to include the 4 columns from v0.29.1. Future column additions should automatically update the bootstrap.
Optionally: add a CI test that simulates the v0.26 → latest upgrade path on a populated brain to catch similar regressions.
Environment:
Repro:
Root cause:
In
src/core/pglite-engine.ts,applyForwardReferenceBootstrap()(around L248) covers columns up to v0.26.5 (deleted_at) but not the 4 columns added in v0.29.1:effective_dateeffective_date_sourceimport_filenamesalience_touched_atThe fail point is in
getPGLiteSchema():This index creation fails because
effective_datecolumn doesn't exist.CREATE TABLE IF NOT EXISTSwon't alter existing tables to add the column, and the bootstrap that's supposed to handle this gap doesn't include the v0.29.1 columns.The forward reference bootstrap was introduced in v0.28.5 ("PGLite upgrade wedge fix") to handle exactly this scenario, but the bootstrap code wasn't updated when v0.29.1 added the new columns. Likely a process gap rather than a fundamental design flaw.
Impact:
PGLite brains created with gbrain ≤v0.28.x cannot upgrade to v0.30 cleanly. They get stuck in MINIONS HALF-INSTALLED state. Both
init --migrate-onlyandapply-migrations --yesfail with the same error.Workaround:
Then re-run
gbrain init --migrate-onlyandgbrain apply-migrations --yes.Suggested fix:
Update
applyForwardReferenceBootstrap()to include the 4 columns from v0.29.1. Future column additions should automatically update the bootstrap.Optionally: add a CI test that simulates the v0.26 → latest upgrade path on a populated brain to catch similar regressions.