128 lines
6.6 KiB
Markdown
128 lines
6.6 KiB
Markdown
# 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*
|