Put partial failure and recovery into the quality gate

209 of 210 seed files loaded is neither a clean success nor a total failure. The important property is to expose the partial failure and make a safe retry possible.

1. Split the failure surface

parse input → transactional/idempotent write → public cache invalidation → health/readiness → deploy smoke

Each stage records its own failure and decides whether the next stage may run. If required content fails, Admin returns 409 and the all-in-one flow does not quietly continue into course seeding.

2. Make data changes retryable

• Use stable keys and ON CONFLICT; do not delete and reinsert existing rows.
• Follow expand/contract: add the column, deploy both code paths, backfill, then strengthen the constraint.
• Exclude values such as publication dates and user-edited fields from the upsert SET when reseeding must preserve them.
• Pair IF NOT EXISTS indexes with real query predicates and apply them to existing databases through Admin’s idempotent migration path.

3. Make recovery a user experience

An operator needs to know which file to retry after a partial success. A user needs current status and retry guidance instead of an empty list or stale cache. Admin’s history records status, processed counts, and errors; the action prevents duplicate clicks while running and keeps keyboard focus usable.

4. Verification criteria

• Running the same seed twice creates no duplicates and does not drift publication dates.
• Intentionally failing one file produces HTTP 409 and leaves the failed file in the response and history.
• A migration failure rolls back its transaction and can be run again.
• Containers start after dependency health, not merely process start, and are checked through /health/ready or a service healthcheck.
• If deploy smoke fails, the previous image tag can be restored.

Only after these criteria pass should the change be reported as complete.

Next

• /notes/data/16-idempotent-migration-recovery