united-tattoo/docs/stories/db-1-sql-migrations-and-backup.md

Establish SQL Migrations (Up/Down) and DB Backup — Brownfield Addition (DB-1)

Story ID: DB-1
Type: Brownfield Story (Single-session)
Date: 2025-09-18
Owner: Product Manager (John)
Related Docs:

• D1 Setup: D1_SETUP.md
• Architecture (Tech): docs/brownfield-architecture-tech.md
• Rollback Strategy: docs/prd/rollback-strategy.md

---

Story Title
Establish SQL Migrations (Up/Down) and DB Backup — Brownfield Addition

User Story
As a developer/operator,
I want a standard migrations structure with up/down scripts and a simple DB backup command,
So that I can safely evolve the schema and quickly rollback or recover if needed.

Story Context

Existing System Integration

• Integrates with: Cloudflare D1 via wrangler, sql/schema.sql as current schema source of truth, npm scripts for db management.
• Technology: Wrangler CLI, D1 bindings (env.DB), SQL files under repo, Node/npm scripts.
• Follows pattern: Project scripts under package.json, operational notes in D1_SETUP.md and PRD rollback strategy.

Acceptance Criteria

Functional Requirements

1. Create a versioned migrations directory: sql/migrations/
   • Include initial baseline migration files derived from current sql/schema.sql:
     • sql/migrations/20250918_0001_initial.sql (UP)
     • sql/migrations/20250918_0001_initial_down.sql (DOWN)
   • UP: creates the schema equivalent to current sql/schema.sql.
   • DOWN: drops tables/indexes created by the UP script in safe reverse order.
2. Add npm scripts in package.json:
   • "db:backup": Exports D1 DB to backups/d1-backup-YYYYMMDD-HHMM.sql using wrangler d1 export.
   • "db:migrate:up": Applies a specified migration file to preview or prod (parameterized or documented).
   • "db:migrate:down": Applies the matching down migration file (preview/prod).
   • "db:migrate:latest": Sequentially applies all UP migrations not yet applied (documented approach; simple first version can be manual sequence).
3. Document exact wrangler commands (preview/prod) in D1_SETUP.md and link from docs/prd/rollback-strategy.md.

Integration Requirements 4. Backups directory: backups/ (git-ignored in .gitignore) is used by db:backup; command succeeds locally against the configured DB.
5. No change to runtime DB access code (lib/db.ts) in this story; focus is structure and scripts only.
6. Migrations can be dry-run on a preview environment before production execution; commands documented.

Quality Requirements 7. Verify "db:backup" produces a timestamped SQL file under backups/ with expected content.
8. Verify applying the UP script on an empty DB creates the schema; applying the DOWN script reverts it.
9. Update D1_SETUP.md with:

• New migrations folder layout
• How to run UP/DOWN (preview/prod)
• How to perform db:backup

10. Update docs/prd/rollback-strategy.md to reference db:backup and migrations rollback steps.

Technical Notes

• Suggested npm scripts (illustrative):
  • "db:backup": "mkdir -p backups && wrangler d1 export united-tattoo > backups/d1-backup-$(date +%Y%m%d-%H%M).sql"
  • "db:migrate:up:preview": "wrangler d1 execute united-tattoo --file=sql/migrations/20250918_0001_initial.sql"
  • "db:migrate:down:preview": "wrangler d1 execute united-tattoo --file=sql/migrations/20250918_0001_initial_down.sql"
  • For production, add --remote or use [env.production] context as required by your wrangler.toml.
• Order and naming convention:
  • YYYYMMDD_NNNN_description.sql to sort deterministically; maintain matching *_down.sql pair.
• Track applied migrations:
  • Minimal approach: maintain a migrations_log table in D1 in a later story; for now, manual sequence is acceptable given small scope.

Definition of Done

• sql/migrations/ directory exists with 0001 UP/DOWN scripts reflecting current schema.
• package.json contains db:backup and migrate script entries (preview/prod documented).
• D1_SETUP.md updated with usage instructions and examples.
• docs/prd/rollback-strategy.md references backup/migration rollback steps.
• Manual verification performed on preview DB: UP then DOWN produce expected effects.

Risk and Compatibility Check

Minimal Risk Assessment

• Primary Risk: DOWN script may drop unintended objects if baseline diverges.
• Mitigation: Generate initial UP/DOWN from current schema.sql and verify on preview DB first.
• Rollback: Use db:backup prior to running UP; restore from backup if needed.

Compatibility Verification

• No breaking runtime change (database structure only when migrations applied).
• No app code dependency in this story.
• Performance impact: none at runtime.

Validation Checklist

Scope Validation

• Single-session implementable (create scripts, wire npm commands, update docs).
• Straightforward integration (wrangler, SQL files).
• Follows existing project scripting conventions.
• No new design/architecture required.

Clarity Check

• Requirements and commands are explicit.
• Integration points documented (D1_SETUP.md, rollback strategy).
• Success criteria testable (UP/DOWN on preview, backup file exists).
• Rollback approach simple (restore backup or apply DOWN).

References

• D1 Wrangler Docs, Project D1_SETUP.md, Rollback Strategy PRD shard

---

Dev Agent Record

Agent Model Used

• Dev: James (Full Stack Developer)

File List

• Added: sql/migrations/20250918_0001_initial.sql
• Added: sql/migrations/20250918_0001_initial_down.sql
• Added: scripts/migrate-latest.mjs
• Modified: package.json
• Modified: D1_SETUP.md
• Modified: docs/prd/rollback-strategy.md
• Modified: .gitignore

Debug Log References

• Preview verification (local D1):
  • Reset with DOWN, then UP → tables present: appointments, artists, availability, file_uploads, portfolio_images, site_settings, users.
  • Final DOWN → only _cf_METADATA remains.
  • Commands used:
    • npx wrangler d1 execute united-tattoo --local --file=sql/migrations/20250918_0001_initial.sql
    • npx wrangler d1 execute united-tattoo --local --file=sql/migrations/20250918_0001_initial_down.sql
    • npx wrangler d1 execute united-tattoo --local --command="SELECT name FROM sqlite_master WHERE type='table' ORDER BY 1;"
  • Note: Executed with elevated permissions due to local wrangler logging outside workspace.

Completion Notes

• Implemented baseline UP/DOWN migrations from current schema.sql.
• Added backup and migration scripts for preview and production, plus latest runner.
• Updated setup and rollback documentation with exact commands.
• Verified local preview DB: UP created schema; DOWN removed it; backup file creation validated using npm run db:backup:local.

Change Log

• 2025-09-18: Implemented DB-1 migrations/backup structure and docs.