Split db-init into pre-schema and post-schema phases

CI dry-run revealed an architectural ordering bug: db-init/004 and
db-init/005 ALTER TABLE the Directus-managed tables (organization_users,
events, etc.), but db-init runs BEFORE schema-apply creates those
tables. On a fresh CI Postgres this fails with "relation does not
exist." Local dev never tripped this because we'd created the tables
via MCP first.

Fix: introduce a post-schema migration phase. Two db-init runs in the
entrypoint, with schema-apply in between:

  1. apply-db-init.sh   db-init/        → positions hypertable + faulty
                                          column (tables Directus does
                                          NOT manage)
  2. schema-apply.sh                    → creates Directus-managed tables
                                          from snapshots/schema.yaml
  3. apply-db-init.sh   db-init-post/   → composite UNIQUE constraints on
                                          the Directus-managed tables
  4. directus bootstrap
  5. directus start

Files moved:
  db-init/004_junction_unique_constraints.sql →
    db-init-post/001_junction_unique_constraints.sql
  db-init/005_event_participation_unique_constraints.sql →
    db-init-post/002_event_participation_unique_constraints.sql

Each ALTER TABLE in the post-schema migrations is now wrapped in a
pg_constraint existence guard for idempotency. This handles the dev DB
where the constraints already exist (from the original 004/005 runs +
the manual psql recovery during task 1.5's destructive-apply
incident). Old 004/005 rows in migrations_applied become orphans —
harmless.

Updates:
- Dockerfile: COPY db-init-post into the image
- entrypoint.sh: 4-step → 5-step flow with the post-schema run between
  schema-apply and bootstrap
- .gitea/workflows/build.yml: dry-run chains all three pre-boot scripts
  (pre-schema → schema-apply → post-schema); path filter includes
  db-init-post/**
- Task specs 1.4 and 1.5 Done sections: updated to reference the new
  db-init-post/ path (db-init/004 → db-init-post/001, etc.)

The reusable runner script (apply-db-init.sh) didn't need to change —
it already accepts DB_INIT_DIR and uses just the basename for the
guard-table key. The two phases share migrations_applied; filenames
don't collide because pre-schema and post-schema use distinct
descriptive names.

Phase 1 is still "done" — this is a Phase 1 architectural correction
exposed by the CI dry-run, not a new task.
This commit is contained in:
2026-05-02 10:47:52 +02:00
parent 82615c0a66
commit e01abfef27
10 changed files with 245 additions and 157 deletions
@@ -1,60 +0,0 @@
-- 004_junction_unique_constraints.sql
-- Composite UNIQUE constraints on the three org-junction tables.
--
-- Why this lives in db-init/ rather than being captured by Directus snapshot:
-- Directus's field-level `is_unique` flag only generates single-column
-- unique constraints. Junction tables need composite uniqueness on the
-- pair (org, target) so the same user/vehicle/device cannot be registered
-- twice within the same org. The snapshot YAML format does NOT capture
-- composite unique constraints, so Directus cannot round-trip them.
-- They belong here, in the same place the positions hypertable's DDL lives.
--
-- Owned by: task 1.4 (org catalog collections). The constraints are part of
-- the data model contract, not a separate Phase 1 migration concern.
--
-- Idempotency: ALTER TABLE ... ADD CONSTRAINT is NOT idempotent. The
-- migrations_applied guard table ensures this file runs at most once per
-- environment. If a constraint already exists (e.g. ad-hoc on an existing
-- stage DB), the operator must INSERT INTO migrations_applied (filename,
-- checksum) VALUES ('004_junction_unique_constraints.sql', '<sha256>') to
-- skip this file on next boot.
ALTER TABLE organization_users
ADD CONSTRAINT organization_users_org_user_unique
UNIQUE (organization_id, user_id);
ALTER TABLE organization_vehicles
ADD CONSTRAINT organization_vehicles_org_vehicle_unique
UNIQUE (organization_id, vehicle_id);
ALTER TABLE organization_devices
ADD CONSTRAINT organization_devices_org_device_unique
UNIQUE (organization_id, device_id);
-- -------------------------------------------------------------------------
-- Assertion block: verify all three constraints landed.
-- -------------------------------------------------------------------------
DO $$ BEGIN
IF NOT EXISTS (
SELECT 1 FROM pg_constraint
WHERE conname = 'organization_users_org_user_unique'
) THEN
RAISE EXCEPTION 'organization_users composite unique constraint missing';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_constraint
WHERE conname = 'organization_vehicles_org_vehicle_unique'
) THEN
RAISE EXCEPTION 'organization_vehicles composite unique constraint missing';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_constraint
WHERE conname = 'organization_devices_org_device_unique'
) THEN
RAISE EXCEPTION 'organization_devices composite unique constraint missing';
END IF;
END $$;
@@ -1,65 +0,0 @@
-- 005_event_participation_unique_constraints.sql
-- Composite UNIQUE constraints on the event-participation collections.
--
-- Same rationale as 004: Directus's `is_unique` flag is single-column only;
-- composite uniqueness lives in db-init/ because the snapshot YAML format
-- does not capture multi-column unique constraints.
--
-- Owned by: task 1.5 (event-participation collections).
ALTER TABLE events
ADD CONSTRAINT events_org_slug_unique
UNIQUE (organization_id, slug);
ALTER TABLE classes
ADD CONSTRAINT classes_event_code_unique
UNIQUE (event_id, code);
ALTER TABLE entries
ADD CONSTRAINT entries_event_race_number_unique
UNIQUE (event_id, race_number);
ALTER TABLE entry_crew
ADD CONSTRAINT entry_crew_entry_user_unique
UNIQUE (entry_id, user_id);
ALTER TABLE entry_devices
ADD CONSTRAINT entry_devices_entry_device_unique
UNIQUE (entry_id, device_id);
-- -------------------------------------------------------------------------
-- Assertion block: verify all five constraints landed.
-- -------------------------------------------------------------------------
DO $$ BEGIN
IF NOT EXISTS (
SELECT 1 FROM pg_constraint WHERE conname = 'events_org_slug_unique'
) THEN
RAISE EXCEPTION 'events composite unique constraint (org, slug) missing';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_constraint WHERE conname = 'classes_event_code_unique'
) THEN
RAISE EXCEPTION 'classes composite unique constraint (event, code) missing';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_constraint WHERE conname = 'entries_event_race_number_unique'
) THEN
RAISE EXCEPTION 'entries composite unique constraint (event, race_number) missing';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_constraint WHERE conname = 'entry_crew_entry_user_unique'
) THEN
RAISE EXCEPTION 'entry_crew composite unique constraint (entry, user) missing';
END IF;
IF NOT EXISTS (
SELECT 1 FROM pg_constraint WHERE conname = 'entry_devices_entry_device_unique'
) THEN
RAISE EXCEPTION 'entry_devices composite unique constraint (entry, device) missing';
END IF;
END $$;