docs(14-01): complete database foundation plan

- Created 14-01-SUMMARY.md with execution results
- Updated STATE.md with plan progress and decisions
- Updated ROADMAP.md progress table (1/6 plans)
- Marked DB-01 and DB-03 requirements complete

.planning/REQUIREMENTS.md

@@ -9,9 +9,9 @@ Requirements for this milestone. Each maps to roadmap phases.
 
 ### Database Migration
 
-- [ ] **DB-01**: Application runs on PostgreSQL instead of SQLite
+- [x] **DB-01**: Application runs on PostgreSQL instead of SQLite
 - [ ] **DB-02**: All service functions use async database operations
-- [ ] **DB-03**: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
+- [x] **DB-03**: Test infrastructure uses PGlite instead of bun:sqlite in-memory databases
 - [ ] **DB-04**: Existing SQLite data can be migrated to Postgres via a one-time script
 - [ ] **DB-05**: Docker Compose provides Postgres for local development
 
@@ -116,9 +116,9 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| DB-01 | Phase 14 | Pending |
+| DB-01 | Phase 14 | Complete |
 | DB-02 | Phase 14 | Pending |
-| DB-03 | Phase 14 | Pending |
+| DB-03 | Phase 14 | Complete |
 | DB-04 | Phase 14 | Pending |
 | DB-05 | Phase 14 | Pending |
 | AUTH-01 | Phase 15 | Pending |

.planning/ROADMAP.md

@@ -123,7 +123,7 @@ Plans:
   4. Docker Compose brings up Postgres alongside the app with a single command for local development
 **Plans:** 6 plans
 Plans:
-- [ ] 14-01-PLAN.md — Schema rewrite (pg-core), DB config (postgres.js), test helper (PGlite), Drizzle config, initial migration
+- [x] 14-01-PLAN.md — Schema rewrite (pg-core), DB config (postgres.js), test helper (PGlite), Drizzle config, initial migration
 - [ ] 14-02-PLAN.md — Docker Compose dev/prod + Dockerfile update for PostgreSQL
 - [ ] 14-03-PLAN.md — All 9 services async conversion + seed + server index
 - [ ] 14-04-PLAN.md — All 9 route handlers async conversion
@@ -195,7 +195,7 @@ Plans:
 | 11. Candidate Ranking | v1.3 | 2/2 | Complete | 2026-03-16 |
 | 12. Comparison View | v1.3 | 1/1 | Complete | 2026-03-17 |
 | 13. Setup Impact Preview | v1.3 | 0/2 | Not started | - |
-| 14. PostgreSQL Migration | v2.0 | 0/6 | Not started | - |
+| 14. PostgreSQL Migration | v2.0 | 1/6 | In progress | - |
 | 15. External Authentication | v2.0 | 0/? | Not started | - |
 | 16. Multi-User Data Model | v2.0 | 0/? | Not started | - |
 | 17. Object Storage | v2.0 | 0/? | Not started | - |

.planning/STATE.md

@@ -26,19 +26,19 @@ See: .planning/PROJECT.md (updated 2026-04-03)
 ## Current Position
 
 Phase: 14 of 18 (PostgreSQL Migration)
-Plan: 0 of ? in current phase
+Plan: 1 of 6 in current phase
-Status: Ready to plan
+Status: Executing
-Last activity: 2026-04-03 — v2.0 roadmap created (Phases 14-18)
+Last activity: 2026-04-04 — Completed 14-01 (Database Foundation)
 
-Progress: [----------] 0% (v2.0 milestone)
+Progress: [=---------] 3% (v2.0 milestone)
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 0 (v2.0 milestone)
+- Total plans completed: 1 (v2.0 milestone)
-- Average duration: --
+- Average duration: 3min
-- Total execution time: --
+- Total execution time: 3min
 
 *Updated after each plan completion*
 
@@ -55,6 +55,12 @@ Key decisions made during v2.0 planning:
 - Separate globalItems table — not a flag on user items table
 - Single-user SQLite mode diverges at v2.0 boundary
 
+Key decisions made during Phase 14 execution:
+
+- postgres.js driver (not node-postgres) for PostgreSQL connection
+- PGlite for in-memory test databases replacing bun:sqlite
+- Separate drizzle-pg/ migration directory from old drizzle/
+
 ### Pending Todos
 
 None active.
@@ -66,6 +72,6 @@ None active.
 
 ## Session Continuity
 
-Last session: 2026-04-04T10:12:41.532Z
+Last session: 2026-04-04T10:19:11Z
-Stopped at: Phase 14 plans created (6 plans, 3 waves)
+Stopped at: Completed 14-01-PLAN.md (Database Foundation)
-Resume file: .planning/phases/14-postgresql-migration/14-01-PLAN.md
+Resume file: .planning/phases/14-postgresql-migration/14-02-PLAN.md

.planning/phases/14-postgresql-migration/14-01-SUMMARY.md

@@ -0,0 +1,120 @@
+---
+phase: 14-postgresql-migration
+plan: 01
+subsystem: database
+tags: [postgresql, drizzle-orm, pglite, postgres-js, migration]
+
+requires:
+  - phase: 13-setup-impact-preview
+    provides: "Complete SQLite-based application"
+provides:
+  - "PostgreSQL schema definitions (13 tables via pg-core)"
+  - "postgres.js database connection with DATABASE_URL"
+  - "PGlite-based async test helper"
+  - "Initial PostgreSQL migration (drizzle-pg/)"
+  - "Async seed function"
+affects: [14-02, 14-03, 14-04, 14-05, 14-06]
+
+tech-stack:
+  added: [postgres (postgres.js driver), "@electric-sql/pglite"]
+  patterns: ["pgTable schema definitions", "async createTestDb() with PGlite", "DATABASE_URL environment variable for connection"]
+
+key-files:
+  created: ["drizzle-pg/0000_fuzzy_shiva.sql"]
+  modified: ["src/db/schema.ts", "src/db/index.ts", "src/db/migrate.ts", "src/db/seed.ts", "drizzle.config.ts", "tests/helpers/db.ts", "package.json", "biome.json"]
+
+key-decisions:
+  - "Used postgres.js (not pg/node-postgres) as PostgreSQL driver for Drizzle ORM"
+  - "PGlite for in-memory test databases replacing bun:sqlite :memory:"
+  - "Migration output directory drizzle-pg/ separate from old drizzle/ directory"
+
+patterns-established:
+  - "All schema tables use pgTable with serial primary keys (except settings/sessions with text PKs)"
+  - "Timestamps use native timestamp type with defaultNow() instead of integer mode:timestamp"
+  - "Test databases created via async createTestDb() returning PGlite-backed Drizzle instance"
+
+requirements-completed: [DB-01, DB-03]
+
+duration: 3min
+completed: 2026-04-04
+---
+
+# Phase 14 Plan 01: Database Foundation Summary
+
+**PostgreSQL schema with 13 pgTable definitions, postgres.js connection, PGlite test infrastructure, and initial migration**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-04T10:15:43Z
+- **Completed:** 2026-04-04T10:19:11Z
+- **Tasks:** 2
+- **Files modified:** 10
+
+## Accomplishments
+- Rewrote all 13 table definitions from sqliteTable to pgTable with correct type mappings (serial, timestamp, doublePrecision, boolean)
+- Established postgres.js connection with DATABASE_URL environment variable
+- Created async PGlite test helper that applies migrations and seeds in-memory
+- Generated initial PostgreSQL migration with 13 CREATE TABLE statements
+- Zero SQLite references remain in database layer files
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Install dependencies and rewrite schema + DB config files** - `3724cf8` (feat)
+2. **Task 2: Rewrite test helper and generate initial PostgreSQL migration** - `3bf1fd7` (feat)
+
+## Files Created/Modified
+- `src/db/schema.ts` - 13 PostgreSQL table definitions using drizzle-orm/pg-core
+- `src/db/index.ts` - postgres.js connection with DATABASE_URL
+- `src/db/migrate.ts` - postgres-js migrator targeting drizzle-pg/
+- `src/db/seed.ts` - Async seed function for default category
+- `drizzle.config.ts` - PostgreSQL dialect config with drizzle-pg/ output
+- `tests/helpers/db.ts` - Async PGlite-backed createTestDb()
+- `package.json` - Added postgres, @electric-sql/pglite; removed better-sqlite3
+- `biome.json` - Added drizzle-pg/ to ignore list
+- `drizzle-pg/0000_fuzzy_shiva.sql` - Initial migration with 13 tables
+
+## Decisions Made
+- Used postgres.js driver (lightweight, ESM-native, good Drizzle integration) over node-postgres
+- PGlite creates ephemeral in-memory Postgres for tests -- no external DB needed
+- Separate migration directory (drizzle-pg/) to avoid conflicts with old SQLite migrations (drizzle/)
+- Added drizzle-pg/ to biome ignore since it contains generated files
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Added drizzle-pg/ to biome ignore list**
+- **Found during:** Task 2 (migration generation)
+- **Issue:** Generated drizzle-pg/ JSON snapshot failed biome formatting (2-space vs tab indent)
+- **Fix:** Added "!drizzle-pg" to biome.json files.includes array (matching existing "!drizzle" pattern)
+- **Files modified:** biome.json
+- **Verification:** `bun run lint` passes clean
+- **Committed in:** 3bf1fd7 (Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Necessary to maintain passing lint. No scope creep.
+
+## Issues Encountered
+- PGlite smoke test exits with code 99 when no explicit `process.exit(0)` is called -- this is a known PGlite cleanup behavior, not a real error. Adding explicit exit resolves it.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Schema and test infrastructure ready for service layer conversion (Plan 14-02)
+- All services can now be updated to use async Drizzle operations against PostgreSQL types
+- PGlite test helper available for all test files to migrate to
+
+## Self-Check: PASSED
+
+All 7 key files verified present. Both task commits (3724cf8, 3bf1fd7) verified in git log.
+
+---
+*Phase: 14-postgresql-migration*
+*Completed: 2026-04-04*