1dc1a1a07a
Phase 1 foundation for the Stargue Publishing Engine (plan v2, BMAD
panel-reviewed 2026-04-19 — 1 APPROVE, 6 REVISE, 0 REJECT; all principles >=3).
- Governance doctrine adopted from DQMS
(.clinerules/12-foundational-principles.md,
.claude/hooks/gate-plan-exit.sh, .claude/skills/bmad-plan/SKILL.md)
- Bun workspaces + Turbo; apps/{mcp-linkedin,scheduler,admin};
packages/{schema,sanitize,linkedin-client,observability}
- Drizzle schema (content, publications, approvals, metrics,
linkedin_tokens, audit, outlet_feature_flags) with idempotency_key
UNIQUE and kill-switch table per TEA/dev panel revisions
- LinkedIn API canon: Posts API /rest/posts (not legacy UGC); OAuth
auth-code without PKCE; secretbox (not sealed-box); Community
Management API as separate approval gate from MDP
- Frontmatter Zod schema (status, language, outlets[], sanitize,
scheduled, version)
- Pino observability with PII redaction
- Expand-then-contract migration runbook
- Plan + panel verdicts mirrored to docs/plans/
- Deferred gates logged (Dokploy PaaS verification, LinkedIn Dev
Portal app registration)
bun install + bun run typecheck both exit 0 across 11 workspaces.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
39 lines
1.7 KiB
Markdown
39 lines
1.7 KiB
Markdown
# Database migrations — runbook
|
|
|
|
**Authoring rule:** every schema change follows **expand-then-contract** sequencing. A breaking change is split into ≥2 migrations with a rollback point between them.
|
|
|
|
## Pattern
|
|
|
|
| Phase | Migration files | What it does | Rollback |
|
|
|---|---|---|---|
|
|
| 1. Expand | `NNNN_expand_<change>.sql` | Add new nullable column / new table / new index. Old code keeps working. | Drop the new addition. |
|
|
| 2. Backfill | `NNNN_backfill_<change>.sql` (if data migration needed) | Populate the new column from existing data. Idempotent. | Re-run or delete column. |
|
|
| 3. Constrain | `NNNN_constrain_<change>.sql` | Add NOT NULL / UNIQUE / FK / CHECK now that data is populated. | Drop the constraint. |
|
|
| 4. Contract | `NNNN_contract_<change>.sql` | Remove the old column / table once no code reads it. **Only after ≥1 deploy cycle of the new code.** | Restore from `pg_dump`. |
|
|
|
|
## Mandatory for every migration
|
|
|
|
- `migrations/NNNN_<name>.sql` — the forward migration.
|
|
- `migrations/NNNN_<name>.down.sql` — the rollback SQL.
|
|
- An entry below in the **Registry** with rationale, linked plan, and rollback cost estimate.
|
|
|
|
## Registry
|
|
|
|
| # | Date | Name | Plan | Forward cost | Rollback cost | Notes |
|
|
|---|---|---|---|---|---|---|
|
|
| — | — | — | — | — | — | No migrations yet — first migration lands in Stage 2.1 |
|
|
|
|
## Rehearsal
|
|
|
|
Stage 2.2 DoD: every schema change is rehearsed end-to-end on staging before production. Command:
|
|
|
|
```bash
|
|
bun run db:migrate:rehearse
|
|
```
|
|
|
|
Rehearsal must cover: forward → backfill (if applicable) → constrain → contract, with a row-count + row-hash check at each step.
|
|
|
|
## Incidents
|
|
|
|
Any migration incident gets a post-mortem in `docs/incidents/YYYY-MM-DD-migration-<name>.md`.
|