costco-grocery-list/docs/DB_MIGRATION_WORKFLOW.md

DB Migration Workflow (External Postgres)

This project uses an external on-prem Postgres database. Migration files are canonical in:

• packages/db/migrations

Preconditions

• DATABASE_URL is set and points to the on-prem Postgres instance.
• psql is installed and available in PATH.
• You are in repo root.

Commands

• Apply pending migrations:
  • npm run db:migrate
• Show migration status:
  • npm run db:migrate:status
• Fail if pending migrations exist:
  • npm run db:migrate:verify

Active migration set

Migration files are applied in lexicographic filename order from packages/db/migrations.

Current baseline files:

• add_display_name_column.sql
• add_image_columns.sql
• add_modified_on_column.sql
• add_notes_column.sql
• create_item_classification_table.sql
• multi_household_architecture.sql

Tracking table

Applied migrations are recorded in:

• schema_migrations(filename text unique, applied_at timestamptz)

Expected operator flow

1. Check status:
   • npm run db:migrate:status
2. Apply pending:
   • npm run db:migrate
3. Verify clean state:
   • npm run db:migrate:verify

Troubleshooting

• DATABASE_URL is required:
  • Export/set DATABASE_URL in your environment.
• psql executable was not found in PATH:
  • Install PostgreSQL client tools and retry.
• SQL failure:
  • Fix migration SQL and rerun; only successful files are recorded in schema_migrations.