# @blackglory/better-sqlite3-migrations

> A utility for database migrations with better-sqlite3

Latest version **0.2.2** (published 2026-02-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install @blackglory/better-sqlite3-migrations
pnpm add @blackglory/better-sqlite3-migrations
yarn add @blackglory/better-sqlite3-migrations
bun add @blackglory/better-sqlite3-migrations
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2026-02-12 |
| First published | 2020-10-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 3 |
| Unpacked size | 14.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Author | BlackGlory |
| Maintainers | black_glory |
| Keywords | migration, migrations, better-sqlite3, up, down, sql |

## Links

- npm: https://www.npmjs.com/package/@blackglory/better-sqlite3-migrations
- Repository: https://github.com/BlackGlory/better-sqlite3-migrations
- Homepage: https://github.com/BlackGlory/better-sqlite3-migrations#readme
- Issues: https://github.com/BlackGlory/better-sqlite3-migrations/issues
- npm.io page: https://npm.io/package/@blackglory/better-sqlite3-migrations

## Dependencies (3)

- [extra-lazy](https://npm.io/package/extra-lazy.md) ^2.0.2
- [extra-utils](https://npm.io/package/extra-utils.md) ^5.20.0
- [@blackglory/prelude](https://npm.io/package/@blackglory/prelude.md) ^0.4.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.2.2 (latest) — 2026-02-12
- 0.2.1 — 2026-02-11
- 0.2.0 — 2026-02-11
- 0.1.20 — 2025-07-21
- 0.1.19 — 2024-09-24
- 0.1.18 — 2023-12-03
- 0.1.17 — 2023-06-10
- 0.1.16 — 2022-11-23
- 0.1.15 — 2022-08-11
- 0.1.14 — 2022-08-11
- 0.1.13 — 2022-08-11
- 0.1.11 — 2022-08-06
- 0.1.10 — 2022-08-01
- 0.1.9 — 2022-02-16
- 0.1.8 — 2022-02-16
- … 8 more at https://npm.io/package/@blackglory/better-sqlite3-migrations/versions

## README

# better-sqlite3-migrations
A utility for database migrations with [better-sqlite3].

The module using [user_version] to record the schema version.

[better-sqlite3]: https://www.npmjs.com/package/better-sqlite3
[user_version]: https://www.sqlite.org/pragma.html#pragma_user_version

## Install
```sh
npm install --save @blackglory/better-sqlite3-migrations
# or
yarn add @blackglory/better-sqlite3-migrations
```

## API
```ts
interface IMigration {
  // An integer starting from 1
  version: number

  up: string | ((db: Database) => void)
  down: string | ((db: Database) => void)
}
```

You may need [migration-files].

[migration-files]: https://github.com/BlackGlory/migration-files

### migrate
```ts
function migrate(
  db: Database
, migrations: IMigration[]
, options?: {
    targetVersion?: number
    throwOnNewerVersion?: boolean = false
  }
): void
```

If `options.targetVersion` is `undefined`,
the maximum version of the `migrations` is used.

When the maximum known migration version is less than the `user_version`,
it means the current instance is outdated.
- When `options.throwOnNewerVersion` is `false` (default),
  it will skip the migration,
  so your outdated instance continues to run.
- When `options.throwOnNewerVersion` is `true`,
  it will throw an error,
  so your outdated instance fails immediately.

#### Can multiple instances migrate in parallel?
Yes, the `user_version` update is visible to every database connection.

Each migration uses `BEGIN IMMEDIATE` to ensure that parallel write transactions fail early.
Therefore, you may need a proper retry strategy.

---
_Source: https://npm.io/package/@blackglory/better-sqlite3-migrations · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._