Migrations And Seeders Backend

Purpose

Schema creation and reference-data seeding run through a small Umzug runner (it replaced sequelize-cli during the TypeScript/ESM migration). This doc covers the developer mechanism: the runner, file conventions, and how to add a migration or seeder. For VM/PM2 operational use (when migrate/seed run on deploy, db:reset recovery), see ../../docs/deployment-vm.md.

Files

Runner: src/db/umzug.ts — builds two Umzug instances (migrator, seeder) and a small CLI.
Reset: src/db/reset.ts — drops every table in the public schema, then re-runs migrator.up() + seeder.up().
Schema snapshot: src/db/initial-schema.ts — DDL snapshot derived from the Sequelize models; the models remain the source of truth.
Migrations: src/db/migrations/*.ts — 20260610000000-initial-schema.ts (creates the full schema from the snapshot) and 20260610010000-add-role-scope-and-user-campus.ts (adds the NOT-NULL roles.scope enum and the nullable users.campusId). Phase 4 adds 20260611000000-policy-documents-and-acknowledgments.ts (the unified policy store + per-version acknowledgments), 20260611010000-audio-files.ts (the audio library) + 20260611060000-audio-files-kinds.ts (the kind enum / nullable url / recipe JSONB), and 20260611040000-add-user-name-prefix.ts (the users.name_prefix honorific enum).
Seeders: src/db/seeders/*.ts — admin-user (the 10 per-role RBAC fixture users), user-roles (the 11 first-class roles, the permission catalog incl. product-feature permissions, the role->permission matrix, role assignment by user id), product-campuses, content-catalog (+ payloads under seeders/content-catalog-data/), rbac-fixtures (the company, campus->org ownership, per-user org/campus links, staff profiles), and 20260611050000-policy-documents-seed.ts (3 safety protocols + 4 handbook policies). Shared fixture definitions live in src/shared/constants/seed-fixtures.ts.

Mechanism

migrator globs migrations/*.{ts,js}; history is tracked in the default SequelizeMeta table via SequelizeStorage.
seeder globs seeders/*.{ts,js}; history is tracked in a separate SequelizeData table.
Each file is ESM TypeScript with a default export { up, down }, each taking (queryInterface, Sequelize). The runner accepts either a default export or top-level up/down.
Tracked names strip the .ts/.js extension, so history is stable whether the runner is executed via tsx (dev, .ts) or compiled (prod, dist/.../*.js).
The glob accepts both .ts and .js, so already-applied entries are not re-run after a build.

CLI And Scripts

src/db/umzug.ts exposes: migrate:up, migrate:down, migrate:pending, seed:up, seed:down. npm scripts wrap them:

Dev (via tsx): db:migrate (migrate:up), db:migrate:undo (migrate:down), db:migrate:pending, db:seed (seed:up), db:seed:undo (seed:down), db:reset (tsx src/db/reset.ts).
Prod (compiled, no tsx): db:migrate:prod (node dist/db/umzug.js migrate:up), db:seed:prod (node dist/db/umzug.js seed:up).

Authoring A New Migration / Seeder

Add src/db/migrations/<timestamp>-<name>.ts (or seeders/...) exporting export default { up, down } with typed (queryInterface, Sequelize) signatures.
Run npm run db:migrate (or db:seed) in dev; verify with db:migrate:pending.
Regenerate database-schema.md after any schema change (it is generated from the models).

Tests

None yet.

database-schema.md (the generated schema reference), backend-architecture.md (DAL layer), ../../docs/deployment-vm.md (operational migrate/seed on the VM).

3.7 KiB Raw Blame History