drizzle-team / drizzle-team/drizzle-orm

[FEATURE]: A hook before migrate() applies that can abort the run

Open
#6,282 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
35.8k
Forks
1.6k
Avg merge
2d 7h
Merged PRs (30d)
4

Description

### Feature hasn't been suggested before.

- [x] I have verified this feature I'm about to request hasn't been suggested before. (#5860 asks for observation hooks on the migrator, this asks for one that can refuse. Discussion #5201 lists a `migrate:files` hook for drizzle-kit plugins with no veto.)

### Describe the enhancement you want to request

A hook on the runtime migrator, `migrate()` in `drizzle-orm`, that runs before any statement executes, receives every pending migration's name, path and SQL, and aborts the whole run when it throws.

Shape, roughly:

```ts
await migrate(db, {
migrationsFolder,
beforeApply: (pending) => {
// pending: { name, path, sql: string[] }[]
// throw to abort, nothing has been applied yet
},
});
```

### Why

A migration file is written by `drizzle-kit generate` from a diff, so it exists before anyone has read it. We apply migrations unattended in a pre-deploy step, and we need a place to refuse a file that fails a policy, before the batch starts.

Our policy is a review line at the end of the file that a session appends after reading the SQL. Others will want a destructive-statement check, a lock-timeout guard, or a schema-name check. One veto hook covers all of them, and none belongs in the library.

Today we wrap `migrate()`: read the folder with `readMigrationFiles`, run the policy over the result, then call `migrate()`. That reads the folder twice and depends on the wrapper being the only path that applies.

Adjacent: a `dryRun` mode that replays the batch inside a rolled-back transaction and reports the rows each statement touched would make the same hook a place to surface data loss before a deploy applies it. Related: #6281 asks for a read-only pending list, #2791 for migration status.

Contributor guide

Open the contributing guide

Research direction

Start at the runtime migrate() entry point in drizzle-orm and compare its pending-migration handling with readMigrationFiles. Define how the beforeApply hook receives each pending migration's name, path, and SQL, and ensure it runs before any statement. Done means a thrown hook error prevents the migration batch from applying.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
database
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.