docs(03): research PostgreSQL support phase

2026-03-24 08:53:53 +01:00
parent 60ca038a7e
commit 535061453b
1 changed files with 575 additions and 0 deletions
--- a/.planning/phases/03-postgresql-support/03-RESEARCH.md
+++ b/.planning/phases/03-postgresql-support/03-RESEARCH.md
@@ -0,0 +1,575 @@
 # Phase 3: PostgreSQL Support - Research
 **Researched:** 2026-03-24
 **Domain:** Go database/sql with pgx/v5 + golang-migrate PostgreSQL dialect
 **Confidence:** HIGH
 ## Summary
 Phase 3 adds PostgreSQL as an alternative backend alongside SQLite. The Store interface and all HTTP handlers are already dialect-neutral (Phase 2 delivered this). The work is entirely in three areas: (1) a new `PostgresStore` struct that implements the existing `Store` interface using PostgreSQL SQL syntax, (2) a separate migration runner for PostgreSQL using `golang-migrate`'s dedicated `pgx/v5` database driver, and (3) wiring in `main.go` to branch on `DATABASE_URL`.
 The critical dialect difference is `CreateTag`: PostgreSQL does not support `LastInsertId()` via `pgx/stdlib`. The `PostgresStore.CreateTag` method must use `QueryRow` with `RETURNING id` instead of `Exec` + `LastInsertId`. Every other SQL translation is mechanical (positional params, `NOW()`, `SERIAL`, `ON CONFLICT ... DO UPDATE` instead of `INSERT OR REPLACE`).
 The golang-migrate ecosystem ships a dedicated `database/pgx/v5` sub-package that wraps a `*sql.DB` opened via `pgx/v5/stdlib`. This fits the established pattern in `migrate.go` exactly — a new `RunPostgresMigrations(db *sql.DB) error` function using the same `iofs` source with an embedded `migrations/postgres` directory.
 **Primary recommendation:** Follow the locked decisions in CONTEXT.md verbatim. The implementation is a straightforward port of `SQLiteStore` with dialect adjustments; the only non-obvious trap is the `LastInsertId` incompatibility in `CreateTag`.
 ---
 <user_constraints>
 ## User Constraints (from CONTEXT.md)
 ### Locked Decisions
 **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
 **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`
 **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)`
 **D-07:** `DATABASE_URL` env var present → PostgreSQL; absent → SQLite with `DB_PATH`
 **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}"`
 **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 (see Architecture Patterns below)
 **D-13:** PostgreSQL migrations embedded via separate `//go:embed migrations/postgres` directive
 **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
 **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
 ### Deferred Ideas (OUT OF SCOPE)
 None — discussion stayed within phase scope.
 </user_constraints>
 ---
 <phase_requirements>
 ## Phase Requirements
 | ID | Description | Research Support |
 |----|-------------|------------------|
 | DB-01 | PostgreSQL is supported as an alternative to SQLite via pgx v5 driver | `pgx/v5/stdlib` confirmed pure-Go, `*sql.DB` compatible; `PostgresStore` implements all 9 Store methods |
 | DB-02 | Database backend is selected via DATABASE_URL env var (present = PostgreSQL, absent = SQLite with DB_PATH) | main.go branching pattern documented; driver registration names confirmed: `"sqlite"` and `"pgx"` |
 | DB-03 | Existing SQLite users can upgrade without data loss (baseline migration represents current schema) | SQLite migration already uses `CREATE TABLE IF NOT EXISTS`; PostgreSQL migration is a fresh baseline for new deployments; no cross-dialect migration needed |
 </phase_requirements>
 ---
 ## Standard Stack
 ### Core
 | Library | Version | Purpose | Why Standard |
 |---------|---------|---------|--------------|
 | `github.com/jackc/pgx/v5` | v5.9.1 (Mar 22 2026) | PostgreSQL driver + `database/sql` adapter via `pgx/v5/stdlib` | De-facto standard Go PostgreSQL driver; pure Go (no CGO); actively maintained; 8,394 packages import it |
 | `github.com/golang-migrate/migrate/v4/database/pgx/v5` | v4.19.1 (same module as existing golang-migrate) | golang-migrate database driver for pgx v5 | Already in project; dedicated pgx/v5 sub-package fits existing `migrate.go` pattern exactly |
 ### Supporting
 | Library | Version | Purpose | When to Use |
 |---------|---------|---------|-------------|
 | `github.com/golang-migrate/migrate/v4/source/iofs` | v4.19.1 (already imported) | Serve embedded FS migration files | Reuse existing pattern from `migrate.go` |
 ### Alternatives Considered
 | Instead of | Could Use | Tradeoff |
 |------------|-----------|----------|
 | `pgx/v5/stdlib` (`database/sql`) | pgx native interface | Native pgx is faster but breaks `Store` interface — rejected by D-02 |
 | `golang-migrate database/pgx/v5` | `golang-migrate database/postgres` | `database/postgres` uses `lib/pq` internally; `database/pgx/v5` uses pgx consistently — use pgx/v5 sub-package |
 | Two separate `RunMigrations` functions | Single function with dialect param | Two functions is simpler, avoids string-switch, each can be `go:embed`-scoped independently — use two functions (see Architecture) |
 **Installation:**
 ```bash
 go get github.com/jackc/pgx/v5@v5.9.1
 go get github.com/golang-migrate/migrate/v4/database/pgx/v5
 ```
 Note: `golang-migrate/migrate/v4` is already in `go.mod` at v4.19.1. Adding the `database/pgx/v5` sub-package pulls from the same module version — no module version conflict.
 **Version verification (current as of 2026-03-24):**
 - `pgx/v5`: v5.9.1 — verified via pkg.go.dev versions tab
 - `golang-migrate/v4`: v4.19.1 — already in go.mod
 ---
 ## Architecture Patterns
 ### Recommended Project Structure
 ```
 pkg/diunwebhook/
 ├── store.go                         # Store interface (unchanged)
 ├── sqlite_store.go                  # SQLiteStore (unchanged)
 ├── postgres_store.go                # PostgresStore (new)
 ├── migrate.go                       # Split: RunSQLiteMigrations + RunPostgresMigrations
 ├── migrations/
 │   ├── sqlite/
 │   │   ├── 0001_initial_schema.up.sql   (exists)
 │   │   └── 0001_initial_schema.down.sql (exists)
 │   └── postgres/
 │       ├── 0001_initial_schema.up.sql   (new)
 │       └── 0001_initial_schema.down.sql (new)
 ├── diunwebhook.go                   (unchanged)
 └── export_test.go                   # Add NewTestPostgresServer (build-tagged)
 cmd/diunwebhook/
 └── main.go                          # Add DATABASE_URL branching
 compose.yml                          # Add postgres profile
 compose.dev.yml                      # Add postgres profile
 ```
 ### Pattern 1: PostgresStore Constructor (no mutex, pool config)
 **What:** Constructor opens pool, sets sensible limits, no mutex (PostgreSQL serializes writes natively).
 **When to use:** Called from `main.go` when `DATABASE_URL` is present.
 ```go
 // Source: CONTEXT.md D-05, D-06 + established SQLiteStore pattern in sqlite_store.go
 package diunwebhook
 import (
    "database/sql"
    "time"
 )
 type PostgresStore struct {
    db *sql.DB
 }
 func NewPostgresStore(db *sql.DB) *PostgresStore {
    db.SetMaxOpenConns(25)
    db.SetMaxIdleConns(5)
    db.SetConnMaxLifetime(5 * time.Minute)
    return &PostgresStore{db: db}
 }
 ```
 ### Pattern 2: RunPostgresMigrations (separate function, separate embed)
 **What:** A dedicated migration runner for PostgreSQL using `golang-migrate`'s `database/pgx/v5` driver. Mirrors `RunMigrations` (which becomes `RunSQLiteMigrations`) exactly.
 **When to use:** Called from `main.go` after `sql.Open("pgx", databaseURL)` when `DATABASE_URL` is set.
 Decision D-12 leaves the split-vs-param choice to researcher. **Recommendation: two separate functions** (`RunSQLiteMigrations` and `RunPostgresMigrations`). Rationale: each function has its own `//go:embed` scope, there's no shared logic to deduplicate, and a string-switch approach adds a code path that can fail at runtime. Rename the existing `RunMigrations` to `RunSQLiteMigrations` for symmetry.
 ```go
 // Source: migrate.go (existing pattern) + golang-migrate pgx/v5 docs
 //go:embed migrations/postgres
 var postgresMigrations embed.FS
 func RunPostgresMigrations(db *sql.DB) error {
    src, err := iofs.New(postgresMigrations, "migrations/postgres")
    if err != nil {
        return err
    }
    driver, err := pgxmigrate.WithInstance(db, &pgxmigrate.Config{})
    if err != nil {
        return err
    }
    m, err := migrate.NewWithInstance("iofs", src, "pgx5", driver)
    if err != nil {
        return err
    }
    if err := m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
        return err
    }
    return nil
 }
 ```
 Import alias: `pgxmigrate "github.com/golang-migrate/migrate/v4/database/pgx/v5"`.
 Driver name string for `NewWithInstance` is `"pgx5"` (matches the registration name in the pgx/v5 driver).
 ### Pattern 3: CreateTag — RETURNING id (CRITICAL)
 **What:** PostgreSQL's pgx driver does not support `LastInsertId()`. `CreateTag` must use `QueryRow` with `RETURNING id`.
 **When to use:** In every `PostgresStore.CreateTag` implementation — this is the most error-prone difference from SQLiteStore.
 ```go
 // Source: pgx issue #1483 + pkg.go.dev pgx/v5/stdlib docs
 func (s *PostgresStore) CreateTag(name string) (Tag, error) {
    var id int
    err := s.db.QueryRow(
        `INSERT INTO tags (name) VALUES ($1) RETURNING id`, name,
    ).Scan(&id)
    if err != nil {
        return Tag{}, err
    }
    return Tag{ID: id, Name: name}, nil
 }
 ```
 ### Pattern 4: AssignTag — ON CONFLICT DO UPDATE (replaces INSERT OR REPLACE)
 **What:** PostgreSQL does not have `INSERT OR REPLACE`. Use `INSERT ... ON CONFLICT (image) DO UPDATE SET tag_id = EXCLUDED.tag_id`.
 **When to use:** `PostgresStore.AssignTag`.
 ```go
 // Source: CONTEXT.md D-04
 _, err := s.db.Exec(
    `INSERT INTO tag_assignments (image, tag_id) VALUES ($1, $2)
     ON CONFLICT (image) DO UPDATE SET tag_id = EXCLUDED.tag_id`,
    image, tagID,
 )
 ```
 ### Pattern 5: main.go DATABASE_URL branching
 ```go
 // Source: CONTEXT.md D-07, D-08, D-09
 databaseURL := os.Getenv("DATABASE_URL")
 var store diun.Store
 if databaseURL != "" {
    db, err := sql.Open("pgx", databaseURL)
    if err != nil {
        log.Fatalf("sql.Open postgres: %v", err)
    }
    if err := diun.RunPostgresMigrations(db); err != nil {
        log.Fatalf("RunPostgresMigrations: %v", err)
    }
    store = diun.NewPostgresStore(db)
    log.Println("Using PostgreSQL database")
 } else {
    dbPath := os.Getenv("DB_PATH")
    if dbPath == "" {
        dbPath = "./diun.db"
    }
    db, err := sql.Open("sqlite", dbPath)
    if err != nil {
        log.Fatalf("sql.Open sqlite: %v", err)
    }
    if err := diun.RunSQLiteMigrations(db); err != nil {
        log.Fatalf("RunSQLiteMigrations: %v", err)
    }
    store = diun.NewSQLiteStore(db)
    log.Printf("Using SQLite database at %s", dbPath)
 }
 ```
 Add `_ "github.com/jackc/pgx/v5/stdlib"` import to `main.go` (blank import registers the `"pgx"` driver name).
 ### Pattern 6: Docker Compose postgres profile
 ```yaml
 # compose.yml — adds postgres profile without breaking default SQLite deploy
 services:
  app:
    image: gitea.jeanlucmakiola.de/makiolaj/diundashboard:latest
    ports:
      - "8080:8080"
    environment:
      - WEBHOOK_SECRET=${WEBHOOK_SECRET:-}
      - PORT=${PORT:-8080}
      - DB_PATH=/data/diun.db
      - DATABASE_URL=${DATABASE_URL:-}
    volumes:
      - diun-data:/data
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
        required: false   # only enforced when postgres profile is active
  postgres:
    image: postgres:17-alpine
    profiles:
      - postgres
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-diun}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-diun}
      POSTGRES_DB: ${POSTGRES_DB:-diundashboard}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-diun}"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped
 volumes:
  diun-data:
  postgres-data:
    profiles:
      - postgres
 ```
 Activate with: `docker compose --profile postgres up -d`
 ### Pattern 7: Build-tagged PostgreSQL integration tests
 ```go
 // Source: CONTEXT.md D-17, D-19 + export_test.go pattern
 //go:build postgres
 package diunwebhook
 import (
    "database/sql"
    "os"
    _ "github.com/jackc/pgx/v5/stdlib"
 )
 func NewTestPostgresServer() (*Server, error) {
    databaseURL := os.Getenv("TEST_DATABASE_URL")
    if databaseURL == "" {
        databaseURL = "postgres://diun:diun@localhost:5432/diundashboard_test?sslmode=disable"
    }
    db, err := sql.Open("pgx", databaseURL)
    if err != nil {
        return nil, err
    }
    if err := RunPostgresMigrations(db); err != nil {
        return nil, err
    }
    store := NewPostgresStore(db)
    return NewServer(store, ""), nil
 }
 ```
 ### Anti-Patterns to Avoid
 - **Using `res.LastInsertId()` after `db.Exec`**: pgx does not implement this — returns an error at runtime. Use `QueryRow(...).Scan(&id)` with `RETURNING id` instead.
 - **Sharing the mutex with PostgresStore**: PostgreSQL handles concurrent writes; adding a mutex is unnecessary and hurts performance.
 - **Using `INSERT OR REPLACE`**: Not valid PostgreSQL syntax. Use `INSERT ... ON CONFLICT ... DO UPDATE SET`.
 - **Using `datetime('now')`**: SQLite function — not valid in PostgreSQL. Use `NOW()` or `CURRENT_TIMESTAMP`.
 - **Using `?` placeholders**: Not valid in PostgreSQL. Use `$1`, `$2`, etc.
 - **Using `INTEGER PRIMARY KEY AUTOINCREMENT`**: Not valid in PostgreSQL. Use `SERIAL` or `BIGSERIAL`.
 - **Forgetting `//go:build postgres` on test files**: Without the build tag, the test file will be compiled for all builds — `pgx/v5/stdlib` import will fail on SQLite-only CI runs.
 - **Calling `RunSQLiteMigrations` on a PostgreSQL connection**: The sqlite migration driver will fail to initialize against a PostgreSQL database.
 ---
 ## Don't Hand-Roll
 | Problem | Don't Build | Use Instead | Why |
 |---------|-------------|-------------|-----|
 | PostgreSQL migration tracking | Custom `schema_version` table | `golang-migrate/v4/database/pgx/v5` | Handles dirty state, locking, version history, rollbacks — all already solved |
 | Connection pooling | Custom pool implementation | `database/sql` built-in pool + `pgx/v5/stdlib` | `database/sql` pool is production-grade; pgx stdlib wraps it correctly |
 | Connection string parsing | Custom URL parser | Pass `DATABASE_URL` directly to `sql.Open("pgx", url)` | pgx parses standard PostgreSQL URI format natively |
 | Dialect detection at runtime | Inspect driver name at query time | Separate store structs with their own SQL | Runtime dialect switching creates test surface, runtime failures; two structs is simpler |
 **Key insight:** The existing `Store` interface already separates the concern — `PostgresStore` is just another implementation. There is nothing to invent.
 ---
 ## Common Pitfalls
 ### Pitfall 1: LastInsertId on PostgreSQL
 **What goes wrong:** `CreateTag` calls `res.LastInsertId()` — pgx returns `ErrNoLastInsertId` at runtime, not compile time.
 **Why it happens:** The `database/sql` `Result` interface defines `LastInsertId()` but pgx does not support it. SQLite does.
 **How to avoid:** In `PostgresStore.CreateTag`, use `QueryRow(...RETURNING id...).Scan(&id)` instead of `Exec` + `LastInsertId`.
 **Warning signs:** Test passes compile, panics or returns error at runtime on tag creation.
 ### Pitfall 2: golang-migrate driver name mismatch
 **What goes wrong:** Passing the wrong database name string to `migrate.NewWithInstance` causes "unknown driver" errors.
 **Why it happens:** The `golang-migrate/database/pgx/v5` driver registers as `"pgx5"`, not `"pgx"` or `"postgres"`.
 **How to avoid:** Use `"pgx5"` as the database name arg to `migrate.NewWithInstance("iofs", src, "pgx5", driver)`.
 **Warning signs:** `migrate.NewWithInstance` returns an error mentioning an unknown driver.
 ### Pitfall 3: pgx/v5/stdlib import not registered
 **What goes wrong:** `sql.Open("pgx", url)` fails with `"unknown driver pgx"`.
 **Why it happens:** The `"pgx"` driver is only registered when `pgx/v5/stdlib` is imported (blank import side effect).
 **How to avoid:** Add `_ "github.com/jackc/pgx/v5/stdlib"` to `main.go` and to any test files that open a `"pgx"` connection.
 **Warning signs:** Runtime error "unknown driver pgx" despite pgx being in go.mod.
 ### Pitfall 4: SQLite `migrate.go` import conflict
 **What goes wrong:** Adding the pgx/v5 migrate driver import to `migrate.go` introduces pgx as a dependency of the SQLite migration path.
 **Why it happens:** Go imports are file-scoped; putting both drivers in one file compiles both.
 **How to avoid:** Put `RunSQLiteMigrations` and `RunPostgresMigrations` in separate files, or at minimum keep the blank driver import for pgx only in the PostgreSQL branch. Alternatively, keep both in `migrate.go` — both drivers are compiled into the binary regardless; this is a binary size trade-off, not a correctness issue.
 **Warning signs:** `modernc.org/sqlite` and `pgx` both appear in a file that should only need one.
 ### Pitfall 5: Docker Compose `required: false` on depends_on
 **What goes wrong:** `app` service fails to start when postgres profile is inactive because `depends_on.postgres` is unconditional.
 **Why it happens:** `depends_on` without `required: false` makes the dependency mandatory even when the postgres profile is not active.
 **How to avoid:** Use `depends_on.postgres.required: false` so the health check dependency is only enforced when the postgres service is actually started. Requires Docker Compose v2.20+.
 **Warning signs:** `docker compose up` (no profile) fails with "service postgres not found".
 ### Pitfall 6: GetUpdates timestamp scanning differences
 **What goes wrong:** `GetUpdates` scans `received_at` and `created` as strings (`createdStr`, `receivedStr`) and then calls `time.Parse(time.RFC3339, ...)`. In the PostgreSQL schema these columns are `TEXT` (by design), so scanning behaves the same. If someone types them as `TIMESTAMPTZ` instead, scanning into a string breaks.
 **Why it happens:** The SQLiteStore scans timestamps as strings because SQLite stores them as TEXT. If the PostgreSQL migration uses `TEXT` for these columns (matching the SQLite schema), the existing scan logic works unchanged in `PostgresStore`.
 **How to avoid:** Use `TEXT NOT NULL` for `received_at`, `acknowledged_at`, and `created` in the PostgreSQL migration, mirroring the SQLite schema exactly. Do not use `TIMESTAMPTZ` unless you also update the scan/format logic.
 **Warning signs:** `sql: Scan error ... converting driver.Value type time.Time into *string`.
 ---
 ## Code Examples
 ### PostgreSQL baseline migration (0001_initial_schema.up.sql)
 ```sql
 -- Source: sqlite/0001_initial_schema.up.sql translated to PostgreSQL dialect
 CREATE TABLE IF NOT EXISTS updates (
    image           TEXT PRIMARY KEY,
    diun_version    TEXT NOT NULL DEFAULT '',
    hostname        TEXT NOT NULL DEFAULT '',
    status          TEXT NOT NULL DEFAULT '',
    provider        TEXT NOT NULL DEFAULT '',
    hub_link        TEXT NOT NULL DEFAULT '',
    mime_type       TEXT NOT NULL DEFAULT '',
    digest          TEXT NOT NULL DEFAULT '',
    created         TEXT NOT NULL DEFAULT '',
    platform        TEXT NOT NULL DEFAULT '',
    ctn_name        TEXT NOT NULL DEFAULT '',
    ctn_id          TEXT NOT NULL DEFAULT '',
    ctn_state       TEXT NOT NULL DEFAULT '',
    ctn_status      TEXT NOT NULL DEFAULT '',
    received_at     TEXT NOT NULL,
    acknowledged_at TEXT
 );
 CREATE TABLE IF NOT EXISTS tags (
    id   SERIAL PRIMARY KEY,
    name TEXT NOT NULL UNIQUE
 );
 CREATE TABLE IF NOT EXISTS tag_assignments (
    image  TEXT PRIMARY KEY,
    tag_id INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE
 );
 ```
 Key differences from SQLite version:
 - `SERIAL PRIMARY KEY` replaces `INTEGER PRIMARY KEY AUTOINCREMENT`
 - All other columns are identical (`TEXT` type used throughout)
 - `ON DELETE CASCADE` is the same — PostgreSQL enforces FK constraints by default (no equivalent of `PRAGMA foreign_keys = ON` needed)
 ### PostgreSQL down migration (0001_initial_schema.down.sql)
 ```sql
 DROP TABLE IF EXISTS tag_assignments;
 DROP TABLE IF EXISTS tags;
 DROP TABLE IF EXISTS updates;
 ```
 Identical to SQLite version.
 ### UpsertEvent (PostgreSQL)
 ```go
 // Positional params $1..$15, acknowledged_at reset to NULL on conflict
 _, err := s.db.Exec(`
    INSERT INTO updates (
        image, diun_version, hostname, status, provider,
        hub_link, mime_type, digest, created, platform,
        ctn_name, ctn_id, ctn_state, ctn_status,
        received_at, acknowledged_at
    ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,NULL)
    ON CONFLICT(image) DO UPDATE SET
        diun_version    = EXCLUDED.diun_version,
        hostname        = EXCLUDED.hostname,
        status          = EXCLUDED.status,
        provider        = EXCLUDED.provider,
        hub_link        = EXCLUDED.hub_link,
        mime_type       = EXCLUDED.mime_type,
        digest          = EXCLUDED.digest,
        created         = EXCLUDED.created,
        platform        = EXCLUDED.platform,
        ctn_name        = EXCLUDED.ctn_name,
        ctn_id          = EXCLUDED.ctn_id,
        ctn_state       = EXCLUDED.ctn_state,
        ctn_status      = EXCLUDED.ctn_status,
        received_at     = EXCLUDED.received_at,
        acknowledged_at = NULL`,
    event.Image, event.DiunVersion, ...
 )
 ```
 ### AcknowledgeUpdate (PostgreSQL)
 ```go
 // NOW() replaces datetime('now'), $1 replaces ?
 res, err := s.db.Exec(`UPDATE updates SET acknowledged_at = NOW() WHERE image = $1`, image)
 ```
 ---
 ## State of the Art
 | Old Approach | Current Approach | When Changed | Impact |
 |--------------|------------------|--------------|--------|
 | `lib/pq` (archived) | `pgx/v5/stdlib` | pgx v4→v5, lib/pq archived ~2023 | pgx is now the consensus standard Go PostgreSQL driver |
 | `golang-migrate database/postgres` (uses lib/pq) | `golang-migrate database/pgx/v5` | golang-migrate added pgx/v5 sub-package | Use the pgx-native driver to avoid a lib/pq dependency |
 | Single global `RunMigrations` | Separate `RunSQLiteMigrations` / `RunPostgresMigrations` | This phase | Each function owns its embed directive and driver import |
 ---
 ## Open Questions
 1. **Rename `RunMigrations` to `RunSQLiteMigrations`**
   - What we know: `RunMigrations` is only called in `main.go` and `export_test.go`. Renaming breaks two call sites.
   - What's unclear: Whether to rename (consistency) or keep old name and add a new `RunPostgresMigrations` (backward compatible for hypothetical external callers).
   - Recommendation: Rename to `RunSQLiteMigrations` — this is internal-only code and symmetry aids comprehension. Update the two call sites.
 2. **`depends_on.required: false` Docker Compose version requirement**
   - What we know: `required: false` under `depends_on` was added in Docker Compose v2.20.
   - What's unclear: Whether the target deployment environment has Compose v2.20+. Docker 29.0.0 (confirmed present) ships with Compose v2.29+ — this is not a concern for the dev machine. Production deployments depend on the user's Docker version.
   - Recommendation: Use `required: false`; document minimum Docker Compose v2.20 in compose.yml comment.
 ---
 ## Environment Availability
 | Dependency | Required By | Available | Version | Fallback |
 |------------|------------|-----------|---------|----------|
 | Docker | Compose postgres profile, integration tests | ✓ | 29.0.0 | — |
 | PostgreSQL server | Integration test execution (`-tags postgres`) | ✗ | — | Tests skip via build tag; Docker Compose spins up postgres for CI |
 | `pg_isready` / psql client | Health check inside postgres container | ✗ (host) | — | `pg_isready` is inside the `postgres:17-alpine` image — not needed on host |
 | Go 1.26 | Build | Not directly measurable from this shell | go.mod specifies 1.26 | — |
 **Missing dependencies with no fallback:**
 - None that block development. PostgreSQL integration tests require a live server but are gated behind `//go:build postgres`.
 **Missing dependencies with fallback:**
 - PostgreSQL server (host): not installed, but not required — tests use build tags, Docker Compose provides the server for integration runs.
 ---
 ## Project Constraints (from CLAUDE.md)
 Directives the planner must verify compliance with:
 - **No CGO**: `CGO_ENABLED=0` in Dockerfile Stage 2. `pgx/v5` is pure Go — this constraint is satisfied. Verify that adding `pgx/v5` does not transitively pull in any CGO package.
 - **Pure Go SQLite driver**: `modernc.org/sqlite` must remain. Adding pgx does not replace it — both coexist.
 - **Database must support both SQLite and PostgreSQL**: This is exactly what Phase 3 delivers via the Store interface.
 - **`database/sql` abstraction**: Both stores use `*sql.DB`. No pgx native interface in handlers.
 - **`net/http` only, no router framework**: No impact from this phase.
 - **`gofmt` enforced**: All new `.go` files must be `gofmt`-clean.
 - **Naming conventions**: New file `postgres_store.go`, new type `PostgresStore`, new constructor `NewPostgresStore`. Test helper `NewTestPostgresServer`. Functions `RunSQLiteMigrations` / `RunPostgresMigrations`.
 - **Error handling**: `http.Error(w, ..., status)` with lowercase messages. Not directly affected — PostgresStore is storage-layer only. `log.Fatalf` in `main.go` for connection/migration failures (matches existing pattern).
 - **No global state**: `PostgresStore` holds `*sql.DB` as struct field, no package-level vars — consistent with Phase 2 refactor.
 - **GSD workflow**: Do not make direct edits outside a GSD phase.
 - **Module name**: `awesomeProject` (in go.mod). Import as `diun "awesomeProject/pkg/diunwebhook"` in main.go.
 ---
 ## Sources
 ### Primary (HIGH confidence)
 - pkg.go.dev/github.com/jackc/pgx/v5 — version confirmed v5.9.1 (Mar 22 2026), stdlib package import path, driver name `"pgx"`, pure Go confirmed
 - pkg.go.dev/github.com/jackc/pgx/v5/stdlib — `sql.Open("pgx", url)` pattern, `LastInsertId` not supported
 - pkg.go.dev/github.com/golang-migrate/migrate/v4/database/pgx/v5 — `WithInstance(*sql.DB, *Config)`, driver registers as `"pgx5"`, v4.19.1
 - github.com/golang-migrate/migrate/blob/master/database/pgx/v5/pgx.go — confirmed `database.Register("pgx5", &db)` registration name
 - Existing codebase: `store.go`, `sqlite_store.go`, `migrate.go`, `export_test.go`, `main.go` — all read directly
 ### Secondary (MEDIUM confidence)
 - github.com/jackc/pgx/issues/1483 — `LastInsertId` not supported by pgx, confirmed by multiple sources
 - Docker Compose docs (docs.docker.com/reference/compose-file/services/) — profiles syntax, depends_on with required: false
 ### Tertiary (LOW confidence)
 - WebSearch results re: Docker Compose `required: false` version requirement — states Compose v2.20; not independently verified against official changelog. However, Docker 29.0.0 (installed) ships Compose v2.29+, so this is moot for the dev machine.
 ## Metadata
 **Confidence breakdown:**
 - Standard stack: HIGH — versions verified via pkg.go.dev on 2026-03-24
 - Architecture: HIGH — based on existing codebase patterns + confirmed library APIs
 - Pitfalls: HIGH for LastInsertId, driver name, import registration (all verified via official sources); MEDIUM for Docker Compose `required: false` version boundary
 **Research date:** 2026-03-24
 **Valid until:** 2026-05-24 (stable ecosystem; pgx and golang-migrate release infrequently)