docs(03-01): complete PostgreSQL store and migration infrastructure plan
- Add 03-01-SUMMARY.md with full execution record - Update STATE.md: advance to plan 2, record metrics and decisions - Update ROADMAP.md: phase 03 in progress (1/2 plans complete) - Update REQUIREMENTS.md: mark DB-01 and DB-03 complete
This commit is contained in:
93
.planning/phases/03-postgresql-support/03-01-SUMMARY.md
Normal file
93
.planning/phases/03-postgresql-support/03-01-SUMMARY.md
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
phase: 03-postgresql-support
|
||||
plan: "01"
|
||||
subsystem: persistence
|
||||
tags: [postgresql, store, migration, pgx]
|
||||
dependency_graph:
|
||||
requires: []
|
||||
provides: [PostgresStore, RunPostgresMigrations, RunSQLiteMigrations]
|
||||
affects: [pkg/diunwebhook/migrate.go, pkg/diunwebhook/postgres_store.go]
|
||||
tech_stack:
|
||||
added: [github.com/jackc/pgx/v5 v5.9.1, golang-migrate pgx/v5 driver]
|
||||
patterns: [Store interface implementation, golang-migrate embedded migrations, pgx/v5 stdlib adapter]
|
||||
key_files:
|
||||
created:
|
||||
- pkg/diunwebhook/postgres_store.go
|
||||
- pkg/diunwebhook/migrations/postgres/0001_initial_schema.up.sql
|
||||
- pkg/diunwebhook/migrations/postgres/0001_initial_schema.down.sql
|
||||
modified:
|
||||
- pkg/diunwebhook/migrate.go
|
||||
- pkg/diunwebhook/export_test.go
|
||||
- go.mod
|
||||
- go.sum
|
||||
decisions:
|
||||
- "PostgresStore uses *sql.DB via pgx/v5/stdlib adapter — no native pgx pool, consistent with SQLiteStore pattern"
|
||||
- "No mutex in PostgresStore — PostgreSQL handles concurrent writes natively (unlike SQLite)"
|
||||
- "Timestamps stored as TEXT in PostgreSQL schema — matches SQLite scan logic, avoids TIMESTAMPTZ type divergence"
|
||||
- "CreateTag uses RETURNING id instead of LastInsertId — pgx driver does not support LastInsertId"
|
||||
- "AssignTag uses ON CONFLICT (image) DO UPDATE instead of INSERT OR REPLACE — standard PostgreSQL upsert"
|
||||
- "Both migration runners compiled into same binary — no build tags needed (both drivers always present)"
|
||||
metrics:
|
||||
duration: "~2.5 minutes"
|
||||
completed: "2026-03-24T08:09:42Z"
|
||||
tasks_completed: 2
|
||||
files_changed: 7
|
||||
---
|
||||
|
||||
# Phase 03 Plan 01: PostgreSQL Store and Migration Infrastructure Summary
|
||||
|
||||
PostgresStore implementing all 9 Store interface methods using pgx/v5 stdlib adapter, plus PostgreSQL migration infrastructure with RunPostgresMigrations and renamed RunSQLiteMigrations.
|
||||
|
||||
## What Was Built
|
||||
|
||||
### PostgresStore (pkg/diunwebhook/postgres_store.go)
|
||||
Full implementation of the Store interface for PostgreSQL:
|
||||
- `NewPostgresStore` constructor with connection pool: `MaxOpenConns(25)`, `MaxIdleConns(5)`, `ConnMaxLifetime(5m)`
|
||||
- All 9 methods: `UpsertEvent`, `GetUpdates`, `AcknowledgeUpdate`, `ListTags`, `CreateTag`, `DeleteTag`, `AssignTag`, `UnassignTag`, `TagExists`
|
||||
- PostgreSQL-native SQL: `$1..$15` positional params, `NOW()`, `RETURNING id`, `ON CONFLICT DO UPDATE`
|
||||
- No `sync.Mutex` — PostgreSQL handles concurrent writes natively
|
||||
|
||||
### PostgreSQL Migrations (pkg/diunwebhook/migrations/postgres/)
|
||||
- `0001_initial_schema.up.sql`: Creates same 3 tables as SQLite (`updates`, `tags`, `tag_assignments`); uses `SERIAL PRIMARY KEY` for `tags.id`; timestamps remain `TEXT` to match scan logic
|
||||
- `0001_initial_schema.down.sql`: Drops all 3 tables in dependency order
|
||||
|
||||
### Updated migrate.go
|
||||
- `RunMigrations` renamed to `RunSQLiteMigrations`
|
||||
- `RunPostgresMigrations` added using `pgxmigrate` driver with `"pgx5"` database name
|
||||
- Second `//go:embed migrations/postgres` directive added for `postgresMigrations`
|
||||
|
||||
## Decisions Made
|
||||
|
||||
| Decision | Rationale |
|
||||
|----------|-----------|
|
||||
| TEXT timestamps in PostgreSQL schema | Avoids scan divergence with SQLiteStore; both stores parse RFC3339 strings identically |
|
||||
| RETURNING id in CreateTag | pgx driver does not implement `LastInsertId`; `RETURNING` is the PostgreSQL-idiomatic approach |
|
||||
| ON CONFLICT (image) DO UPDATE in AssignTag | Replaces SQLite's `INSERT OR REPLACE`; functionally equivalent upsert in standard SQL |
|
||||
| No mutex in PostgresStore | PostgreSQL connection pool + MVCC handles concurrency; mutex would serialize unnecessarily |
|
||||
| Both drivers compiled into binary | Simpler than build tags; binary size cost acceptable for a server binary |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 1 - Bug] Updated export_test.go to use renamed function**
|
||||
- **Found during:** Task 1 verification
|
||||
- **Issue:** `go vet ./pkg/diunwebhook/` failed because `export_test.go` still referenced `RunMigrations` (renamed to `RunSQLiteMigrations`). The plan's acceptance criteria requires `go vet` to exit 0, which takes precedence over the instruction to defer export_test.go changes to Plan 02.
|
||||
- **Fix:** Updated both `NewTestServer` and `NewTestServerWithSecret` in `export_test.go` to call `RunSQLiteMigrations`
|
||||
- **Files modified:** `pkg/diunwebhook/export_test.go`
|
||||
- **Commit:** 95b64b4
|
||||
|
||||
## Verification Results
|
||||
|
||||
- `go build ./pkg/diunwebhook/` exits 0
|
||||
- `go vet ./pkg/diunwebhook/` exits 0
|
||||
- PostgreSQL migration UP contains `SERIAL PRIMARY KEY`, all 3 tables
|
||||
- PostgreSQL migration DOWN contains `DROP TABLE IF EXISTS` for all 3 tables
|
||||
- `go.mod` contains `github.com/jackc/pgx/v5 v5.9.1`
|
||||
- `migrate.go` exports both `RunSQLiteMigrations` and `RunPostgresMigrations`
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — this plan creates implementation code, not UI stubs.
|
||||
|
||||
## Self-Check: PASSED
|
||||
Reference in New Issue
Block a user