orm-preflight

# orm-preflight

[![npm](https://img.shields.io/npm/v/orm-preflight)](https://www.npmjs.com/package/orm-preflight)
[![CI](https://github.com/sikandar100/orm-preflight/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sikandar100/orm-preflight/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/sikandar100/orm-preflight/badge)](https://scorecard.dev/viewer/?uri=github.com/sikandar100/orm-preflight)
[![License: MIT](https://img.shields.io/npm/l/orm-preflight)](https://github.com/sikandar100/orm-preflight/blob/main/LICENSE)

Preflight safety checks for TypeORM migrations: catch data loss and locking before you merge.

Documentation: https://sikandar100.github.io/orm-preflight/

Changing a column's length in TypeORM can delete all of its data. When a column's type or length
changes, TypeORM's migration generator drops the column and adds it again
([typeorm/typeorm#3357](https://github.com/typeorm/typeorm/issues/3357)). The migration looks
harmless in review and passes every test on an empty database. orm-preflight catches that, and
other migrations that lose data, lock busy tables, or break a rolling deploy, before you merge.

```
src/migrations/1727100000000-WidenUserName.ts
  7:30  error  no-drop-and-recreate-column
        "users"."name" is dropped and re-added in the same migration. Every existing value in this column will be lost.
        Why:  TypeORM drops and re-adds a column when its type or length changes, instead of changing it in place. The new column starts empty.
        Safe: Change the type in place: ALTER TABLE "users" ALTER COLUMN "name" TYPE varchar(255). Widening a varchar, or changing varchar to text, does not rewrite the table. ...
        Docs: https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-drop-and-recreate-column.md

  8:30  error  no-add-not-null-without-default
        "users"."name" is added as NOT NULL without a default. The migration fails as soon as "users" has any rows.
        ...

2 errors, 0 warnings in 1 migration
```

## Install and run

```sh
npm install --save-dev orm-preflight
npx orm-preflight "src/migrations/*.ts"
```

Node.js 20 or newer. Without arguments, orm-preflight checks the `migrations` globs from its
config, or every `migrations` folder in the project.

To start on an existing project without fixing its history, run `npx orm-preflight init` first
(see [Adopting on an existing project](#adopting-on-an-existing-project)).

## What it catches

| Rule                                                                                                                                                    | Reports                                                                               |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Data loss**                                                                                                                                           |                                                                                       |
| [`no-drop-and-recreate-column`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-drop-and-recreate-column.md)                       | A column dropped and added again in one migration                                     |
| [`possible-rename-data-loss`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/possible-rename-data-loss.md)                           | One column dropped and another added, with no data copied (warning)                   |
| [`no-drop-column`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-drop-column.md)                                                 | A dropped column                                                                      |
| [`no-drop-table`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-drop-table.md)                                                   | A dropped table                                                                       |
| [`no-truncate`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-truncate.md)                                                       | `TRUNCATE` or `clearTable()`                                                          |
| [`typeorm/no-changecolumn-recreate`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/typeorm/no-changecolumn-recreate.md)             | `changeColumn()` that drops and re-adds the column                                    |
| **Deploy safety**                                                                                                                                       |                                                                                       |
| [`no-rename-column`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-rename-column.md)                                             | A renamed column                                                                      |
| [`no-rename-table`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-rename-table.md)                                               | A renamed table                                                                       |
| **Locking (PostgreSQL)**                                                                                                                                |                                                                                       |
| [`require-concurrent-index`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/require-concurrent-index.md)                             | `CREATE INDEX` without `CONCURRENTLY`                                                 |
| [`concurrent-index-transaction`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/concurrent-index-transaction.md)                     | `CONCURRENTLY` where it runs inside a transaction                                     |
| [`no-add-not-null-without-default`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-add-not-null-without-default.md)               | A `NOT NULL` column added without a default                                           |
| [`no-volatile-default`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-volatile-default.md)                                       | A column added with a volatile default, or as serial, identity, or generated          |
| [`no-unsafe-column-type-change`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-unsafe-column-type-change.md)                     | A column type change that rewrites the table                                          |
| [`require-not-valid-foreign-key`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/require-not-valid-foreign-key.md)                   | A foreign key added without `NOT VALID`                                               |
| [`no-set-not-null`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-set-not-null.md)                                               | `SET NOT NULL` on an existing column                                                  |
| [`require-not-valid-check`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/require-not-valid-check.md)                               | A CHECK constraint added without `NOT VALID`                                          |
| [`require-concurrent-unique`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/require-concurrent-unique.md)                           | A unique constraint or primary key added in place                                     |
| [`require-concurrent-index-drop`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/require-concurrent-index-drop.md)                   | `DROP INDEX` without `CONCURRENTLY` (warning)                                         |
| [`no-blocking-maintenance`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/no-blocking-maintenance.md)                               | `VACUUM FULL`, `CLUSTER`, or `REINDEX` without `CONCURRENTLY`                         |
| [`enum-value-used-in-same-transaction`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/enum-value-used-in-same-transaction.md)       | A new enum value used before the transaction that adds it commits                     |
| [`require-lock-timeout`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/require-lock-timeout.md)                                     | A change to an existing table without `lock_timeout` (off, opt-in)                    |
| [`typeorm/no-enum-recreate`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/typeorm/no-enum-recreate.md)                             | TypeORM 0.3's enum change by recreating the type (warning)                            |
| **Correctness**                                                                                                                                         |                                                                                       |
| [`typeorm/transaction-override-forbidden`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/typeorm/transaction-override-forbidden.md) | `transaction` set on a migration in transaction mode `"all"`                          |
| [`typeorm/invalid-migration-name`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/typeorm/invalid-migration-name.md)                 | A migration name without a 13-digit timestamp                                         |
| [`unanalyzable-statement`](https://github.com/sikandar100/orm-preflight/blob/main/docs/rules/unanalyzable-statement.md)                                 | A statement