Add Alembic migration testing against Postgres in CI

forgejo_admin commented

2026-03-14 18:34:49 +00:00

Owner

Lineage

plan-pal-e-docs → Phase 7 (CI/Infra Hardening)
todo-migration-testing-ci-pal-e-docs — existing TODO note

Repo

forgejo_admin/pal-e-docs

User Story

As a developer merging schema changes
I want CI to test Alembic migrations against Postgres before deploy
So that broken migrations never reach production (two past incidents: 2026-02-26, 2026-03-02)

Context

The CI test step uses PALDOCS_DATABASE_PATH=":memory:" (SQLite) — zero migration testing against Postgres. pal-e-docs has been on Postgres since 2026-03-08. Two production incidents from untested migrations that worked on SQLite but failed on Postgres. The test step runs ruff + pytest but never runs alembic upgrade head. Woodpecker supports service containers (like postgres:17), so we can spin up a real Postgres for migration testing.

File Targets

Files the agent should modify or create:

.woodpecker.yaml — add migration-test step between test and build-and-push

Files the agent should NOT touch:

alembic/ — migration scripts are correct, just untested in CI
k8s/ — deployment manifests

Acceptance Criteria

Woodpecker pipeline has a migration-test step using a Postgres 17 service container
Step runs alembic upgrade head against the Postgres service
Step verifies clean state (no pending migrations)
Step runs on both push and pull_request events
Failed migration blocks the pipeline (step is before build-and-push)

Test Expectations

Integration test: trigger a pipeline on a PR and verify the migration-test step passes
Negative test: intentionally break a migration and verify the step fails
Run command: pipeline runs automatically on push/PR

Constraints

Use Woodpecker services: block for Postgres container (not a step)
Match the PALDOCS_DATABASE_URL format used in production: postgresql+psycopg://user:pass@host:5432/dbname
Step image should be python:3.12-slim or similar (needs pip install for alembic + psycopg)
Keep existing test step on SQLite :memory: — it's fast for unit tests. Migration test is a separate concern.

Checklist

PR opened
Tests pass
No unrelated changes

pal-e-docs — project this affects
todo-migration-testing-ci-pal-e-docs — existing TODO
todo-pal-e-docs-deployment-reliability — parent reliability TODO
phase-pal-e-docs-ci-infra — Phase 7

### Lineage `plan-pal-e-docs` → Phase 7 (CI/Infra Hardening) `todo-migration-testing-ci-pal-e-docs` — existing TODO note ### Repo `forgejo_admin/pal-e-docs` ### User Story As a developer merging schema changes I want CI to test Alembic migrations against Postgres before deploy So that broken migrations never reach production (two past incidents: 2026-02-26, 2026-03-02) ### Context The CI test step uses `PALDOCS_DATABASE_PATH=":memory:"` (SQLite) — zero migration testing against Postgres. pal-e-docs has been on Postgres since 2026-03-08. Two production incidents from untested migrations that worked on SQLite but failed on Postgres. The test step runs ruff + pytest but never runs `alembic upgrade head`. Woodpecker supports service containers (like `postgres:17`), so we can spin up a real Postgres for migration testing. ### File Targets Files the agent should modify or create: - `.woodpecker.yaml` — add `migration-test` step between `test` and `build-and-push` Files the agent should NOT touch: - `alembic/` — migration scripts are correct, just untested in CI - `k8s/` — deployment manifests ### Acceptance Criteria - [ ] Woodpecker pipeline has a `migration-test` step using a Postgres 17 service container - [ ] Step runs `alembic upgrade head` against the Postgres service - [ ] Step verifies clean state (no pending migrations) - [ ] Step runs on both `push` and `pull_request` events - [ ] Failed migration blocks the pipeline (step is before `build-and-push`) ### Test Expectations - [ ] Integration test: trigger a pipeline on a PR and verify the migration-test step passes - [ ] Negative test: intentionally break a migration and verify the step fails - Run command: pipeline runs automatically on push/PR ### Constraints - Use Woodpecker `services:` block for Postgres container (not a step) - Match the `PALDOCS_DATABASE_URL` format used in production: `postgresql+psycopg://user:pass@host:5432/dbname` - Step image should be `python:3.12-slim` or similar (needs pip install for alembic + psycopg) - Keep existing test step on SQLite `:memory:` — it's fast for unit tests. Migration test is a separate concern. ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `pal-e-docs` — project this affects - `todo-migration-testing-ci-pal-e-docs` — existing TODO - `todo-pal-e-docs-deployment-reliability` — parent reliability TODO - `phase-pal-e-docs-ci-infra` — Phase 7