docs(03): capture phase context

.planning/phases/03-postgresql-support/03-CONTEXT.md

@@ -0,0 +1,127 @@
+# Phase 3: PostgreSQL Support - Context
+
+**Gathered:** 2026-03-24
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Add PostgreSQL as an alternative database backend alongside SQLite. Users with PostgreSQL infrastructure can point DiunDashboard at a Postgres database via `DATABASE_URL` and the dashboard works identically to the SQLite deployment. Existing SQLite users upgrade without data loss.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### PostgreSQL driver interface
+- **D-01:** Use `pgx/v5/stdlib` as the database/sql adapter — matches SQLiteStore's `*sql.DB` pattern so PostgresStore has the same constructor signature (`*sql.DB` in, Store out)
+- **D-02:** Do NOT use pgx native interface directly — keeping both stores on `database/sql` means the Store interface stays unchanged and `NewServer(store Store, ...)` works identically
+
+### SQL dialect handling
+- **D-03:** Each store implementation has its own raw SQL — no runtime dialect switching, no query builder, no shared SQL templates
+- **D-04:** PostgreSQL-specific syntax differences handled in PostgresStore methods:
+  - `SERIAL` instead of `INTEGER PRIMARY KEY AUTOINCREMENT` for tags.id
+  - `$1, $2, $3` positional params instead of `?` placeholders
+  - `NOW()` or `CURRENT_TIMESTAMP` instead of `datetime('now')` for acknowledged_at
+  - `ON CONFLICT ... DO UPDATE SET` syntax is compatible (PostgreSQL 9.5+)
+  - `INSERT ... ON CONFLICT DO UPDATE` for UPSERT (same pattern, different param style)
+  - `INSERT ... ON CONFLICT` for tag assignments instead of `INSERT OR REPLACE`
+
+### Connection pooling
+- **D-05:** PostgresStore does NOT use a mutex — PostgreSQL handles concurrent writes natively
+- **D-06:** Use `database/sql` default pool settings with sensible overrides: `MaxOpenConns(25)`, `MaxIdleConns(5)`, `ConnMaxLifetime(5 * time.Minute)` — appropriate for a low-traffic self-hosted dashboard
+
+### Database selection logic (main.go)
+- **D-07:** `DATABASE_URL` env var present → PostgreSQL; absent → SQLite with `DB_PATH` (already decided in STATE.md)
+- **D-08:** No separate `DB_DRIVER` variable — the presence of `DATABASE_URL` is the switch
+- **D-09:** Startup log clearly indicates which backend is active: `"Using PostgreSQL database"` vs `"Using SQLite database at {path}"`
+
+### Migration structure
+- **D-10:** Separate migration directories: `migrations/sqlite/` (exists) and `migrations/postgres/` (new)
+- **D-11:** PostgreSQL baseline migration `0001_initial_schema.up.sql` creates the same 3 tables with PostgreSQL-native types
+- **D-12:** `RunMigrations` becomes dialect-aware or split into `RunSQLiteMigrations`/`RunPostgresMigrations` — researcher should determine best approach
+- **D-13:** PostgreSQL migrations embedded via separate `//go:embed migrations/postgres` directive
+
+### Docker Compose integration
+- **D-14:** Use Docker Compose profiles — `docker compose --profile postgres up` activates the postgres service
+- **D-15:** Default compose (no profile) remains SQLite-only for simple deploys
+- **D-16:** Compose file includes a `postgres` service with health check, and the app service gets `DATABASE_URL` when the profile is active
+
+### Testing strategy
+- **D-17:** PostgresStore integration tests use a `//go:build postgres` build tag — they only run when a PostgreSQL instance is available
+- **D-18:** CI can optionally run `-tags postgres` with a postgres service container; SQLite tests always run
+- **D-19:** Test helper `NewTestPostgresServer()` creates a test database and runs migrations, similar to `NewTestServer()` for SQLite
+
+### Claude's Discretion
+- Exact PostgreSQL connection pool tuning beyond the defaults in D-06
+- Whether to split RunMigrations into two functions or use a dialect parameter
+- Error message formatting for PostgreSQL connection failures
+- Whether to add a health check endpoint that verifies database connectivity
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Store interface and patterns
+- `pkg/diunwebhook/store.go` — Store interface definition (9 methods that PostgresStore must implement)
+- `pkg/diunwebhook/sqlite_store.go` — Reference implementation with exact SQL operations to port
+- `pkg/diunwebhook/migrate.go` — Current migration runner (SQLite-only, needs PostgreSQL support)
+
+### Schema
+- `pkg/diunwebhook/migrations/sqlite/0001_initial_schema.up.sql` — Baseline schema to translate to PostgreSQL dialect
+
+### Wiring
+- `cmd/diunwebhook/main.go` — Current startup wiring (SQLite-only, needs DATABASE_URL branching)
+- `pkg/diunwebhook/export_test.go` — Test server helpers (pattern for NewTestPostgresServer)
+
+### Deployment
+- `Dockerfile` — Current build (may need postgres client libs or build tag)
+- `compose.yml` — Production compose (needs postgres profile)
+- `compose.dev.yml` — Dev compose (needs postgres profile for local dev)
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `Store` interface in `store.go`: PostgresStore implements the same 9 methods — no handler changes needed
+- `SQLiteStore` in `sqlite_store.go`: Reference for all SQL operations — port each method to PostgreSQL dialect
+- `RunMigrations` in `migrate.go`: Pattern for migration runner with `embed.FS` + `iofs` + `golang-migrate`
+- `NewTestServer()` in `export_test.go`: Pattern for test helper — clone for PostgreSQL variant
+
+### Established Patterns
+- `database/sql` as the DB abstraction layer — PostgresStore follows the same pattern
+- `sync.Mutex` for SQLite write serialization — NOT needed for PostgreSQL (native concurrent writes)
+- `//go:embed` for migration files — same pattern for `migrations/postgres/`
+- Constructor returns concrete type implementing Store: `NewSQLiteStore(*sql.DB) *SQLiteStore` → `NewPostgresStore(*sql.DB) *PostgresStore`
+
+### Integration Points
+- `main.go` line 24: `sql.Open("sqlite", dbPath)` — add conditional for `sql.Open("pgx", databaseURL)`
+- `main.go` line 29: `diun.RunMigrations(db)` — needs to call the right migration runner
+- `main.go` line 33: `diun.NewSQLiteStore(db)` — needs to call `diun.NewPostgresStore(db)` when using PostgreSQL
+- `Dockerfile` Stage 2: May need `CGO_ENABLED=0` to remain — verify pgx/v5/stdlib is pure Go
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — open to standard approaches. The core constraint is functional parity: every operation that works on SQLite must work identically on PostgreSQL.
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope.
+
+</deferred>
+
+---
+
+*Phase: 03-postgresql-support*
+*Context gathered: 2026-03-24 via auto mode*

.planning/phases/03-postgresql-support/03-DISCUSSION-LOG.md

@@ -0,0 +1,87 @@
+# Phase 3: PostgreSQL Support - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-03-24
+**Phase:** 03-postgresql-support
+**Areas discussed:** PostgreSQL driver interface, SQL dialect handling, Connection pooling, Docker Compose integration, Testing strategy
+**Mode:** Auto (all selections made by Claude using recommended defaults)
+
+---
+
+## PostgreSQL Driver Interface
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| pgx/v5/stdlib (database/sql adapter) | Matches SQLiteStore's *sql.DB pattern, Store interface unchanged | ✓ |
+| pgx native interface | More features (COPY, batch), but different API from SQLiteStore | |
+| lib/pq | Legacy driver, less maintained | |
+
+**User's choice:** [auto] pgx/v5/stdlib — recommended for consistency with existing database/sql pattern
+**Notes:** Keeping both stores on database/sql means identical constructor signatures and no Store interface changes.
+
+---
+
+## SQL Dialect Handling
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Separate SQL per store | Each store has its own raw SQL, no shared templates | ✓ |
+| Runtime dialect switching | Single store with if/else for dialect differences | |
+| Query builder (squirrel/goqu) | Abstract SQL differences behind builder API | |
+
+**User's choice:** [auto] Separate SQL per store — recommended per project constraint (no ORM/query builder)
+**Notes:** PROJECT.md explicitly states "No ORM or query builder — raw SQL per store implementation."
+
+---
+
+## Connection Pooling
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Standard pool defaults | MaxOpenConns(25), MaxIdleConns(5), ConnMaxLifetime(5m) | ✓ |
+| Minimal single-connection | Match SQLite's MaxOpenConns(1) | |
+| Configurable via env vars | Let users tune pool settings | |
+
+**User's choice:** [auto] Standard pool defaults — appropriate for low-traffic self-hosted dashboard
+**Notes:** PostgreSQL handles concurrent writes natively, so no mutex needed unlike SQLiteStore.
+
+---
+
+## Docker Compose Integration
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Docker Compose profiles | `--profile postgres` activates postgres service | ✓ |
+| Separate compose file | compose.postgres.yml alongside compose.yml | |
+| Always include postgres | Postgres service always defined, user enables via DATABASE_URL | |
+
+**User's choice:** [auto] Docker Compose profiles — keeps simple deploys unchanged, opt-in for postgres
+**Notes:** ROADMAP success criterion #4 states "optional postgres service profile."
+
+---
+
+## Testing Strategy
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Build tag `//go:build postgres` | Tests only run when postgres available | ✓ |
+| Testcontainers (auto-start postgres) | No external dependency needed | |
+| Mock store for postgres tests | No real postgres needed, but less confidence | |
+
+**User's choice:** [auto] Build tag — simplest approach, CI optionally runs with `-tags postgres`
+**Notes:** Matches existing test pattern where SQLite tests always run. PostgreSQL tests are additive.
+
+---
+
+## Claude's Discretion
+
+- Exact PostgreSQL connection pool tuning beyond defaults
+- RunMigrations split strategy (two functions vs dialect parameter)
+- Error message formatting for connection failures
+- Health check endpoint (optional)
+
+## Deferred Ideas
+
+None — discussion stayed within phase scope.