@sqb/migrator 5.0.7 → 6.0.0

package/README.md

@@ -1,23 +1,49 @@
-<center>
-<p>
+<p style="text-align:center">
   <img src="https://user-images.githubusercontent.com/3836517/32965280-1a2b63ce-cbe7-11e7-8ee1-ba47313503c5.png" width="500px" alt="SQB Logo"/>
 </p>
-</center>
 
 <br>
 
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
-[![Build Status][travis-image]][travis-url]
+[![CI Tests][ci-test-image]][ci-test-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
-[![Dependencies][dependencies-image]][dependencies-url]
-[![DevDependencies][devdependencies-image]][devdependencies-url]
-[![Package Quality][quality-image]][quality-url]
 
 ## About SQB
 
 SQB is an extensible, multi-dialect SQL query builder and Database connection wrapper for NodeJS.
 
+## About @sqb/migrator
+
+`@sqb/migrator` is a schema/data migration runner for SQB. A `MigrationPackage` describes an
+ordered set of versioned migrations, each made up of one or more tasks:
+
+- a raw SQL script (a `.sql` file, or an inline string/function),
+- a data-insert task (`{ tableName, rows }`), or
+- a custom function that runs arbitrary code against the connection.
+
+Migrations and tasks can be declared inline or discovered from disk via glob patterns (e.g.
+`v*/migration.json` + `*.task.sql`). `DbMigrator.execute()` loads the package, compares its
+migrations against the target database's tracked version, and applies everything up to an
+optional `targetVersion` in order — recording progress (and per-task success/error events) in a
+`migration_summary` / `migration_events` table pair it creates automatically. Migration scripts
+can reference `$(schema)`, `$(tablespace)` and other variables that get substituted per-run.
+
+```ts
+import { DbMigrator } from '@sqb/migrator';
+
+const migrator = new DbMigrator();
+await migrator.execute({
+  connection: { dialect: 'postgres', database: 'mydb' },
+  migrationPackage: {
+    name: 'my-app',
+    migrations: ['migrations/v*/migration.json'],
+  },
+});
+```
+
+Currently only PostgreSQL is supported, via the bundled `PgMigrationAdapter`.
+
 ## Main goals
 
 - Single code base for any sql based database
@@ -41,7 +67,7 @@ $ npm install @sqb/migrator --save
 
 ## Node Compatibility
 
-- node >= 16.x
+- node >= 20.x
 
 ### License
 
@@ -49,17 +75,9 @@ SQB is available under [MIT](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/@sqb/migrator.svg
 [npm-url]: https://npmjs.org/package/@sqb/migrator
-[travis-image]: https://img.shields.io/travis/sqbjs/@sqb/migrator/master.svg
-[travis-url]: https://travis-ci.org/sqbjs/@sqb/migrator
-[coveralls-image]: https://img.shields.io/coveralls/sqbjs/@sqb/migrator/master.svg
-[coveralls-url]: https://coveralls.io/r/sqbjs/@sqb/migrator
 [downloads-image]: https://img.shields.io/npm/dm/@sqb/migrator.svg
 [downloads-url]: https://npmjs.org/package/@sqb/migrator
-[gitter-image]: https://badges.gitter.im/sqbjs/@sqb/migrator.svg
-[gitter-url]: https://gitter.im/sqbjs/@sqb/migrator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-[dependencies-image]: https://david-dm.org/sqbjs/@sqb/migrator/status.svg
-[dependencies-url]: https://david-dm.org/sqbjs/@sqb/migrator
-[devdependencies-image]: https://david-dm.org/sqbjs/@sqb/migrator/dev-status.svg
-[devdependencies-url]: https://david-dm.org/sqbjs/@sqb/migrator?type=dev
-[quality-image]: http://npm.packagequality.com/shield/@sqb/migrator.png
-[quality-url]: http://packagequality.com/#?package=@sqb/migrator
+[ci-test-image]: https://github.com/panates/sqb/actions/workflows/test.yml/badge.svg
+[ci-test-url]: https://github.com/panates/sqb/actions/workflows/test.yml
+[coveralls-image]: https://coveralls.io/repos/github/sqbjs/sqb/badge.svg?branch=master
+[coveralls-url]: https://coveralls.io/github/sqbjs/sqb?branch=master

package/adapters/pg-migration-adapter.d.ts

@@ -35,6 +35,11 @@ export declare class PgMigrationAdapter extends MigrationAdapter {
     writeEvent(event: MigrationAdapter.Event): Promise<void>;
     executeTask(migrationPackage: MigrationPackage, migration: Migration, task: MigrationTask, variables: Record<string, any>): Promise<void>;
     backupDatabase(): Promise<void>;
+    /**
+     * Serializes concurrent migration runs against the same package using a
+     * Postgres session-level advisory lock, so two processes migrating the
+     * same schema at once can't race on the summary table bookkeeping.
+     */
     lockSchema(): Promise<void>;
     restoreDatabase(): Promise<void>;
     unlockSchema(): Promise<void>;

package/adapters/pg-migration-adapter.js

@@ -5,6 +5,15 @@ import { MigrationAdapter } from '../migration-adapter.js';
 import { isCustomMigrationTask, isInsertDataMigrationTask, isSqlScriptMigrationTask, MigrationPackage, } from '../migration-package.js';
 import { MigrationStatus } from '../types.js';
 const pgAdapter = new PgAdapter();
+// Quotes a (possibly schema-qualified, e.g. "myschema.mytable") Postgres
+// identifier so reserved words / mixed case / special characters in a
+// migration task's tableName or row keys don't break the generated SQL.
+function quoteIdent(name) {
+    return name
+        .split('.')
+        .map(part => '"' + part.replace(/"/g, '""') + '"')
+        .join('.');
+}
 export class PgMigrationAdapter extends MigrationAdapter {
     _infoSchema = 'public';
     _version = 0;
@@ -52,7 +61,10 @@ export class PgMigrationAdapter extends MigrationAdapter {
                     r.rows?.[0]?.current_schema || 'public';
             }
             // Check if migration schema
-            await connection.query(`CREATE SCHEMA IF NOT EXISTS ${adapter.infoSchema} AUTHORIZATION postgres;`);
+            // No AUTHORIZATION clause - let it default to the connecting role,
+            // since hardcoding a specific owner (e.g. "postgres") makes this
+            // fail with a permission error for any non-superuser connection.
+            await connection.query(`CREATE SCHEMA IF NOT EXISTS ${adapter.infoSchema};`);
             // Create summary table if not exists
             await connection.execute(`
 CREATE TABLE IF NOT EXISTS ${adapter.summaryTableFull}
@@ -118,7 +130,7 @@ CREATE TABLE IF NOT EXISTS ${adapter.eventTableFull}
             params.push(info.status);
             sql += ',\n  status = $' + params.length;
         }
-        if (info.version && info.version !== this.version) {
+        if (info.version != null && info.version !== this.version) {
             params.push(info.version);
             sql += ',\n  current_version = $' + params.length;
         }
@@ -132,7 +144,7 @@ CREATE TABLE IF NOT EXISTS ${adapter.eventTableFull}
             await this._connection.query(sql, { params });
             if (info.status)
                 this._status = info.status;
-            if (info.version)
+            if (info.version != null)
                 this._version = info.version;
         }
     }
@@ -207,19 +219,27 @@ CREATE TABLE IF NOT EXISTS ${adapter.eventTableFull}
     backupDatabase() {
         return Promise.resolve(undefined);
     }
-    lockSchema() {
-        return Promise.resolve(undefined);
+    /**
+     * Serializes concurrent migration runs against the same package using a
+     * Postgres session-level advisory lock, so two processes migrating the
+     * same schema at once can't race on the summary table bookkeeping.
+     */
+    async lockSchema() {
+        await this._connection.query('SELECT pg_advisory_lock(hashtext($1)::bigint)', { params: [this.infoSchema + '.' + this.packageName] });
+        // Another process may have advanced the tracked version while we were
+        // waiting for the lock - re-read it now that we hold the lock.
+        await this.refresh();
     }
     restoreDatabase() {
         return Promise.resolve(undefined);
     }
-    unlockSchema() {
-        return Promise.resolve(undefined);
+    async unlockSchema() {
+        await this._connection.query('SELECT pg_advisory_unlock(hashtext($1)::bigint)', { params: [this.infoSchema + '.' + this.packageName] });
     }
     rowToSql(tableName, row) {
         let sql = '';
         const keys = Object.keys(row);
-        sql += `insert into ${tableName} (${keys}) values (`;
+        sql += `insert into ${quoteIdent(tableName)} (${keys.map(quoteIdent).join(', ')}) values (`;
         for (let i = 0; i < keys.length; i++) {
             sql += (i ? ', ' : '') + stringifyValueForSQL(row[keys[i]]);
         }

package/db-migrator.js

@@ -12,7 +12,7 @@ export class DbMigrator extends AsyncEventEmitter {
         if (minVersion === Number.MAX_SAFE_INTEGER)
             minVersion = 0;
         const maxVersion = migrationPackage.migrations.reduce((a, m) => Math.max(a, m.version), 0);
-        const targetVersion = Math.min(options?.targetVersion || Number.MAX_SAFE_INTEGER, maxVersion);
+        const targetVersion = Math.min(options?.targetVersion ?? Number.MAX_SAFE_INTEGER, maxVersion);
         if (targetVersion && targetVersion < minVersion) {
             // noinspection ExceptionCaughtLocallyJS
             throw new Error(`Version mismatch. Target schema version (${targetVersion}) is lower than ` +

package/migration-package.js

@@ -40,6 +40,12 @@ export var MigrationPackage;
                 }
             }
             srcMigrations.sort((a, b) => a.version - b.version);
+            const seenVersions = new Set();
+            for (const m of srcMigrations) {
+                if (seenVersions.has(m.version))
+                    throw new Error(`Migration package "${asyncConfig.name}" has more than one migration defined for version ${m.version}`);
+                seenVersions.add(m.version);
+            }
             for (const migration of srcMigrations) {
                 const trgMigration = {
                     baseDir: '',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sqb/migrator",
   "description": "Database migrator for SQB",
-  "version": "5.0.7",
+  "version": "6.0.0",
   "author": "Panates",
   "license": "Apache-2.0",
   "dependencies": {
@@ -12,9 +12,9 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@sqb/builder": "^5.0.7",
-    "@sqb/connect": "^5.0.7",
-    "@sqb/postgres": "^5.0.7"
+    "@sqb/builder": "^6.0.0",
+    "@sqb/connect": "^6.0.0",
+    "@sqb/postgres": "^6.0.0"
   },
   "type": "module",
   "module": "./index.js",

package/utils/get-calling-filename.js

@@ -1,11 +1,16 @@
 const PATH_PATTERN = /^(?:file:\/\/)?(.+)$/;
 export function getCallingFilename(position = 0) {
     position++;
-    if (position >= Error.stackTraceLimit)
-        return '';
+    const oldStackTraceLimit = Error.stackTraceLimit;
     const oldPrepareStackTrace = Error.prepareStackTrace;
+    // Force the limit deep enough for this call regardless of any ambient
+    // Error.stackTraceLimit set elsewhere in the process - otherwise a small
+    // ambient limit makes this silently return '' and callers fall back to
+    // the wrong base directory.
+    Error.stackTraceLimit = position + 1;
     Error.prepareStackTrace = (_, stack) => stack;
     const stack = new Error().stack;
+    Error.stackTraceLimit = oldStackTraceLimit;
     Error.prepareStackTrace = oldPrepareStackTrace;
     if (stack !== null && typeof stack === 'object') {
         // stack[0] holds this file