Dealer_Onboarding_Backend/scripts/migrations/README.md

Database Migrations

This folder holds versioned, incremental database migrations for environments that already have a populated schema (UAT / production). On a fresh dev box, npm run migrate (destructive sync({ force: true })) is still the fastest route — the model definitions in src/database/models/ remain the source of truth for the desired schema.

Workflow

Goal	Command
Fresh / dev: drop everything, recreate from models	npm run migrate
Mark every migration file here as already-applied	npm run migrate:baseline
Apply only the migrations not yet recorded in DB	npm run migrate:up
List applied vs pending	npm run migrate:status
Scaffold a new migration file	npm run migrate:create -- <snake_case_name>

A typical post-fresh-setup sequence is therefore:

npm run migrate           # drop + recreate
npm run migrate:baseline  # stamp this folder's files as already applied
npm run seed:all          # seed master data

After every subsequent deploy on the same DB:

npm run migrate:up        # apply only the new migrations

File naming convention

<YYYYMMDDHHMMSS>_<snake_case_description>.ts

Examples:

• 20260526143000_add_finance_kyc_column.ts
• 20260601090000_drop_legacy_questionnaire_column.ts

The runner sorts files lexicographically, so the timestamp prefix dictates execution order. Always use UTC when manually creating timestamps; the scaffolder (npm run migrate:create) emits a current-time UTC stamp for you.

Authoring a migration

1. Run npm run migrate:create -- add_finance_kyc_column.
2. Edit the generated file — implement up({ sequelize }).
3. Update the corresponding Sequelize model so fresh migrate runs produce the same end state.
4. Commit both the migration and the model changes in the same PR.
5. On every environment that holds real data, run npm run migrate:up.

The runner records each successful migration in the migrations table ({ name, appliedAt, checksum }) so re-runs are safe and idempotent at the runner level — independently of the migration's own SQL.