@blackglory/sqlite3-migrations 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 BlackGlory <woshenmedoubuzhidao@blackglory.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# sqlite3-migrations
+A utility for database migrations with [sqlite3].
+
+The module using [user_version] to record the schema version.
+
+[sqlite3]: https://www.npmjs.com/package/sqlite3
+[user_version]: https://www.sqlite.org/pragma.html#pragma_user_version
+
+## Install
+```sh
+npm install --save @blackglory/sqlite3-migrations
+# or
+yarn add @blackglory/sqlite3-migrations
+```
+
+## API
+```ts
+interface IMigration {
+  version: number
+  up: string | ((db: Database) => PromiseLike<void>)
+  down: string | ((db: Database) => PromiseLike<void>)
+}
+```
+
+You may need [migration-files].
+
+[migration-files]: https://github.com/BlackGlory/migration-files
+
+### migrate
+```ts
+function migrate(db: Database, migrations: IMigration[], targetVersion?: number): void
+```
+
+If targetVersion is `undefined`, then use the maximum version of migrations.
+
+## FAQ
+### Can multiple instances migrate in parallel?
+Yes, the `user_version` update is visible to every database connection.
+When the maximum migration version is less than the `user_version` (which means it is an obsolete instance), it will skip the migration.
+
+You may need a proper retry strategy,
+because each migration uses `BEGIN IMMEDIATE` to ensure that parallel write transactions fail early.

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './migrate.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export * from './migrate.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA"}

package/lib/migrate.d.ts

@@ -0,0 +1,7 @@
+import type { Database } from 'sqlite3';
+export interface IMigration {
+    version: number;
+    up: string | ((db: Database) => PromiseLike<void>);
+    down: string | ((db: Database) => PromiseLike<void>);
+}
+export declare function migrate(db: Database, migrations: IMigration[], targetVersion?: number): Promise<void>;

package/lib/migrate.js

@@ -0,0 +1,89 @@
+import { assert, isFunction } from '@blackglory/prelude';
+import { promisify } from 'extra-promise';
+export async function migrate(db, migrations, targetVersion = getMaximumVersion(migrations)) {
+    const run = promisify(db.run.bind(db));
+    const exec = promisify(db.exec.bind(db));
+    const get = promisify(db.get.bind(db));
+    const maxVersion = getMaximumVersion(migrations);
+    await run('BEGIN IMMEDIATE');
+    try {
+        while (true) {
+            const done = await migrate(targetVersion, maxVersion);
+            if (done)
+                break;
+        }
+        await run('COMMIT');
+    }
+    catch (e) {
+        await run('ROLLBACK');
+        throw e;
+    }
+    async function migrate(targetVersion, maxVersion) {
+        const currentVersion = await getDatabaseVersion();
+        if (maxVersion < currentVersion) {
+            return true;
+        }
+        else {
+            if (currentVersion === targetVersion) {
+                return true;
+            }
+            else if (currentVersion < targetVersion) {
+                await upgrade();
+                return false;
+            }
+            else {
+                await downgrade();
+                return false;
+            }
+        }
+    }
+    async function upgrade() {
+        const currentVersion = await getDatabaseVersion();
+        const targetVersion = currentVersion + 1;
+        const migration = migrations.find(x => x.version === targetVersion);
+        assert(migration, `Cannot find migration for version ${targetVersion}`);
+        try {
+            if (isFunction(migration.up)) {
+                await migration.up(db);
+            }
+            else {
+                await exec(migration.up);
+            }
+        }
+        catch (e) {
+            console.error(`Upgrade from version ${currentVersion} to version ${targetVersion} failed.`);
+            throw e;
+        }
+        await setDatabaseVersion(targetVersion);
+    }
+    async function downgrade() {
+        const currentVersion = await getDatabaseVersion();
+        const targetVersion = currentVersion - 1;
+        const migration = migrations.find(x => x.version === currentVersion);
+        assert(migration, `Cannot find migration for version ${targetVersion}`);
+        try {
+            if (isFunction(migration.down)) {
+                await migration.down(db);
+            }
+            else {
+                await exec(migration.down);
+            }
+        }
+        catch (e) {
+            console.error(`Downgrade from version ${currentVersion} to version ${targetVersion} failed.`);
+            throw e;
+        }
+        await setDatabaseVersion(targetVersion);
+    }
+    async function getDatabaseVersion() {
+        const row = await get('PRAGMA user_version;');
+        return row.user_version;
+    }
+    async function setDatabaseVersion(version) {
+        await run(`PRAGMA user_version = ${version}`);
+    }
+}
+function getMaximumVersion(migrations) {
+    return migrations.reduce((max, cur) => Math.max(cur.version, max), 0);
+}
+//# sourceMappingURL=migrate.js.map

package/lib/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@blackglory/sqlite3-migrations",
+  "version": "0.1.0",
+  "description": "A utility for database migrations with sqlite3",
+  "keywords": [
+    "migration",
+    "migrations",
+    "sqlite3",
+    "up",
+    "down",
+    "sql"
+  ],
+  "files": [
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "repository": "git@github.com:BlackGlory/sqlite3-migrations.git",
+  "author": "BlackGlory <woshenmedoubuzhidao@blackglory.me>",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "scripts": {
+    "prepare": "ts-patch install -s",
+    "lint": "eslint --ext .js,.jsx,.ts,.tsx --quiet src __tests__",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --runInBand --config jest.config.cjs",
+    "prepublishOnly": "run-s prepare clean build",
+    "clean": "rimraf lib",
+    "build": "tsc --project tsconfig.build.json",
+    "release": "standard-version"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "run-s prepare clean lint build test",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "devDependencies": {
+    "@blackglory/jest-resolver": "^0.3.1",
+    "@commitlint/cli": "^18.4.3",
+    "@commitlint/config-conventional": "^18.4.3",
+    "@types/jest": "^29.5.11",
+    "@types/node": "18",
+    "@typescript-eslint/eslint-plugin": "^6.14.0",
+    "@typescript-eslint/parser": "^6.14.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^8.55.0",
+    "husky": "4",
+    "jest": "^29.7.0",
+    "jest-resolve": "^29.7.0",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^5.0.5",
+    "sqlite3": "^5.1.6",
+    "standard-version": "^9.5.0",
+    "ts-jest": "^29.1.1",
+    "ts-patch": "^3.1.1",
+    "typescript": "^5.3.3",
+    "typescript-transform-paths": "^3.4.6"
+  },
+  "dependencies": {
+    "@blackglory/prelude": "^0.3.4",
+    "extra-promise": "^6.0.8"
+  },
+  "peerDependencies": {
+    "sqlite3": "^5.1.6"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './migrate.js'

package/src/migrate.ts

@@ -0,0 +1,111 @@
+import type { Database } from 'sqlite3'
+import { assert, isFunction } from '@blackglory/prelude'
+import { promisify } from 'extra-promise'
+
+export interface IMigration {
+  version: number
+  up: string | ((db: Database) => PromiseLike<void>)
+  down: string | ((db: Database) => PromiseLike<void>)
+}
+
+export async function migrate(
+  db: Database
+, migrations: IMigration[]
+, targetVersion: number = getMaximumVersion(migrations)
+): Promise<void> {
+  const run = promisify(db.run.bind(db))
+  const exec = promisify(db.exec.bind(db))
+  const get = promisify(db.get.bind(db))
+
+  const maxVersion = getMaximumVersion(migrations)
+
+  await run('BEGIN IMMEDIATE')
+  try {
+    while (true) {
+      const done = await migrate(targetVersion, maxVersion)
+      if (done) break
+    }
+
+    await run('COMMIT')
+  } catch (e) {
+    await run('ROLLBACK')
+    throw e
+  }
+
+  async function migrate(
+    targetVersion: number
+  , maxVersion: number
+  ): Promise<boolean> {
+    const currentVersion = await getDatabaseVersion()
+    if (maxVersion < currentVersion) {
+      return true
+    } else {
+      if (currentVersion === targetVersion) {
+        return true
+      } else if (currentVersion < targetVersion) {
+        await upgrade()
+        return false
+      } else {
+        await downgrade()
+        return false
+      }
+    }
+  }
+
+  async function upgrade(): Promise<void> {
+    const currentVersion = await getDatabaseVersion()
+    const targetVersion = currentVersion + 1
+
+    const migration = migrations.find(x => x.version === targetVersion)
+    assert(migration, `Cannot find migration for version ${targetVersion}`)
+
+    try {
+      if (isFunction(migration.up)) {
+        await migration.up(db)
+      } else {
+        await exec(migration.up)
+      }
+    } catch (e) {
+      console.error(`Upgrade from version ${currentVersion} to version ${targetVersion} failed.`)
+      throw e
+    }
+    await setDatabaseVersion(targetVersion)
+  }
+
+  async function downgrade(): Promise<void> {
+    const currentVersion = await getDatabaseVersion()
+    const targetVersion = currentVersion - 1
+
+    const migration = migrations.find(x => x.version === currentVersion)
+    assert(migration, `Cannot find migration for version ${targetVersion}`)
+
+    try {
+      if (isFunction(migration.down)) {
+        await migration.down(db)
+      } else {
+        await exec(migration.down)
+      }
+    } catch (e) {
+      console.error(`Downgrade from version ${currentVersion} to version ${targetVersion} failed.`)
+      throw e
+    }
+    await setDatabaseVersion(targetVersion)
+  }
+
+  async function getDatabaseVersion(): Promise<number> {
+    const row = await get('PRAGMA user_version;') as {
+      user_version: number
+    }
+
+    return row.user_version
+  }
+
+  async function setDatabaseVersion(version: number): Promise<void> {
+    // PRAGMA不支持变量
+    await run(`PRAGMA user_version = ${ version }`)
+  }
+}
+
+function getMaximumVersion(migrations: IMigration[]): number {
+  return migrations.reduce((max, cur) => Math.max(cur.version, max), 0)
+}