docs(03): capture phase context
This commit is contained in:
127
.planning/phases/03-postgresql-support/03-CONTEXT.md
Normal file
127
.planning/phases/03-postgresql-support/03-CONTEXT.md
Normal file
@@ -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*
|
||||
Reference in New Issue
Block a user