# Migrations Runner Package

Sequelize database migration management using Sequelize CLI + Umzug. Contains ~1395 migrations.

## Commands

```bash
pnpm create-migration-on-main my-migration-name    # Create new migration
pnpm local-migrate-on-main                          # Run pending migrations
pnpm local-undo-migration-on-main                   # Undo last migration
pnpm migration-status-on-main                       # Check migration status
```

## Migration Naming

Format: `{YYYYMMDDHHmmss}-{descriptive-name}.js`

Examples:
- `20251226092249-rename-audience-sementation-query-to-audience-segmentation-query.js`
- `20251203121906-migrate-view-call-to-CF.js`
- `20251202154335-add-last-run-column-BotHandlerForUserEvents.js`

## Migration Structure

All migrations are plain JavaScript in `src/main-migrations/`:

```javascript
'use strict';

/** @type {import('sequelize-cli').Migration} */
module.exports = {
    async up(queryInterface, Sequelize) {
        // addColumn, createTable, addIndex, raw queries, etc.
    },
    async down(queryInterface, Sequelize) {
        // Rollback logic
    },
};
```

## Guidelines

- Migrations are irreversible in practice. Prefer additive changes (add column, add table).
- If a destructive migration is needed (drop column, rename), propose a multi-step rollout.
- Always implement both `up` and `down` methods.
- Build before running: migrations execute from `build/main-migrations/`, not `src/`.
- Run `pnpm clean` before migrating to avoid running migrations from other branches.
- Requires `.env` with database credentials (`DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`, `DB_NAME`).
- Always confirm with the user before creating or modifying migrations.

## Safe Column Migrations (NOT NULL & type changes)

**RULE — ALWAYS APPLY.** Never run a bare `ALTER COLUMN ... SET NOT NULL` or a bare `ALTER COLUMN ... TYPE ...` (e.g. `int → bigint`) in a single migration — both block all reads/writes under `ACCESS EXCLUSIVE` (full scan or full rewrite) and cause outages on large tables. Follow the step-by-step playbooks in [`alter-table.md`](./alter-table.md) before writing any such migration.

See also: root AGENTS.md, common AGENTS.md. For extracted packages: `humand-packages/scheduled-actions/AGENTS.md`.