51 lines
1.4 KiB
Markdown
51 lines
1.4 KiB
Markdown
# 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`.
|