postgres-schema-migrations 6.0.0

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationError = exports.loadMigrationFiles = exports.migrate = exports.createDb = void 0;
+var create_1 = require("./create");
+Object.defineProperty(exports, "createDb", { enumerable: true, get: function () { return create_1.createDb; } });
+var migrate_1 = require("./migrate");
+Object.defineProperty(exports, "migrate", { enumerable: true, get: function () { return migrate_1.migrate; } });
+var files_loader_1 = require("./files-loader");
+Object.defineProperty(exports, "loadMigrationFiles", { enumerable: true, get: function () { return files_loader_1.loadMigrationFiles; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "MigrationError", { enumerable: true, get: function () { return types_1.MigrationError; } });

package/dist/load-sql-from-js.d.ts

@@ -0,0 +1 @@
+export declare const loadSqlFromJs: (filePath: string) => string;

package/dist/load-sql-from-js.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSqlFromJs = void 0;
+const path = require("path");
+const loadSqlFromJs = (filePath) => {
+    const migrationModule = require(filePath);
+    if (!migrationModule.generateSql) {
+        throw new Error(`Invalid javascript migration file: '${path.basename(filePath)}'.
+It must to export a 'generateSql' function.`);
+    }
+    const generatedValue = migrationModule.generateSql();
+    if (typeof generatedValue !== "string") {
+        throw new Error(`Invalid javascript migration file: '${path.basename(filePath)}'.
+'generateSql' function must return a string literal.`);
+    }
+    return generatedValue;
+};
+exports.loadSqlFromJs = loadSqlFromJs;

package/dist/migrate.d.ts

@@ -0,0 +1,13 @@
+import { Config, MigrateDBConfig, Migration } from "./types";
+/**
+ * Run the migrations.
+ *
+ * If `dbConfig.ensureDatabaseExists` is true then `dbConfig.database` will be created if it
+ * does not exist.
+ *
+ * @param dbConfig Details about how to connect to the database
+ * @param migrationsDirectory Directory containing the SQL migration files
+ * @param config Extra configuration
+ * @returns Details about the migrations which were run
+ */
+export declare function migrate(dbConfig: MigrateDBConfig, migrationsDirectory: string, config?: Config): Promise<Array<Migration>>;

package/dist/migrate.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrate = void 0;
+const pg = require("pg");
+const sql_template_strings_1 = require("sql-template-strings");
+const create_1 = require("./create");
+const files_loader_1 = require("./files-loader");
+const run_migration_1 = require("./run-migration");
+const validation_1 = require("./validation");
+const with_connection_1 = require("./with-connection");
+const with_lock_1 = require("./with-lock");
+const splitTableName = (tableName) => {
+    const parts = tableName.split(".");
+    if (parts.length > 1) {
+        return [parts[0], parts[1]];
+    }
+    else {
+        return ["public", tableName];
+    }
+};
+/**
+ * Run the migrations.
+ *
+ * If `dbConfig.ensureDatabaseExists` is true then `dbConfig.database` will be created if it
+ * does not exist.
+ *
+ * @param dbConfig Details about how to connect to the database
+ * @param migrationsDirectory Directory containing the SQL migration files
+ * @param config Extra configuration
+ * @returns Details about the migrations which were run
+ */
+async function migrate(dbConfig, migrationsDirectory, config = {}) {
+    const log = config.logger != null
+        ? config.logger
+        : () => {
+            //
+        };
+    if (dbConfig == null) {
+        throw new Error("No config object");
+    }
+    if (typeof migrationsDirectory !== "string") {
+        throw new Error("Must pass migrations directory as a string");
+    }
+    const intendedMigrations = await files_loader_1.loadMigrationFiles(migrationsDirectory, log, config.schema);
+    if ("client" in dbConfig) {
+        // we have been given a client to use, it should already be connected
+        return with_lock_1.withAdvisoryLock(log, runMigrations(intendedMigrations, log, config.schema))(dbConfig.client);
+    }
+    if (typeof dbConfig.database !== "string" ||
+        typeof dbConfig.user !== "string" ||
+        typeof dbConfig.password !== "string" ||
+        typeof dbConfig.host !== "string" ||
+        typeof dbConfig.port !== "number") {
+        throw new Error("Database config problem");
+    }
+    if (dbConfig.ensureDatabaseExists === true) {
+        // Check whether database exists
+        const { user, password, host, port } = dbConfig;
+        const client = new pg.Client({
+            database: dbConfig.defaultDatabase != null
+                ? dbConfig.defaultDatabase
+                : "postgres",
+            user,
+            password,
+            host,
+            port,
+        });
+        const runWith = with_connection_1.withConnection(log, async (connectedClient) => {
+            const result = await connectedClient.query({
+                text: "SELECT 1 FROM pg_database WHERE datname=$1",
+                values: [dbConfig.database],
+            });
+            if (result.rowCount !== 1) {
+                await create_1.runCreateQuery(dbConfig.database, log)(connectedClient);
+            }
+        });
+        await runWith(client);
+    }
+    {
+        const client = new pg.Client(dbConfig);
+        client.on("error", (err) => {
+            log(`pg client emitted an error: ${err.message}`);
+        });
+        const runWith = with_connection_1.withConnection(log, with_lock_1.withAdvisoryLock(log, runMigrations(intendedMigrations, log, config.schema)));
+        return runWith(client);
+    }
+}
+exports.migrate = migrate;
+function runMigrations(intendedMigrations, log, schemaName = "public") {
+    return async (client) => {
+        try {
+            const migrationTableName = `${schemaName}.migrations`;
+            log("Starting migrations");
+            const appliedMigrations = await fetchAppliedMigrationFromDB(migrationTableName, client, log);
+            validation_1.validateMigrationHashes(intendedMigrations, appliedMigrations);
+            const migrationsToRun = filterMigrations(intendedMigrations, appliedMigrations);
+            const completedMigrations = [];
+            for (const migration of migrationsToRun) {
+                log(`Starting migration: ${migration.id} ${migration.name}`);
+                const result = await run_migration_1.runMigration(migrationTableName, client, log)(migration);
+                log(`Finished migration: ${migration.id} ${migration.name}`);
+                completedMigrations.push(result);
+            }
+            logResult(completedMigrations, log);
+            log("Finished migrations");
+            return completedMigrations;
+        }
+        catch (e) {
+            const error = new Error(`Migration failed. Reason: ${e.message}`);
+            error.cause = e;
+            throw error;
+        }
+    };
+}
+/** Queries the database for migrations table and retrieve it rows if exists */
+async function fetchAppliedMigrationFromDB(migrationTableName, client, log) {
+    let appliedMigrations = [];
+    if (await doesTableExist(client, migrationTableName)) {
+        log(`Migrations table with name '${migrationTableName}' exists, filtering not applied migrations.`);
+        const { rows } = await client.query(`SELECT * FROM ${migrationTableName} ORDER BY id`);
+        appliedMigrations = rows;
+    }
+    else {
+        log(`Migrations table with name '${migrationTableName}' hasn't been created,
+so the database is new and we need to run all migrations.`);
+    }
+    return appliedMigrations;
+}
+/** Work out which migrations to apply */
+function filterMigrations(migrations, appliedMigrations) {
+    const notAppliedMigration = (migration) => !appliedMigrations[migration.id];
+    return migrations.filter(notAppliedMigration);
+}
+/** Logs the result */
+function logResult(completedMigrations, log) {
+    if (completedMigrations.length === 0) {
+        log("No migrations applied");
+    }
+    else {
+        log(`Successfully applied migrations: ${completedMigrations.map(({ name }) => name)}`);
+    }
+}
+/** Check whether table exists in postgres - http://stackoverflow.com/a/24089729 */
+async function doesTableExist(client, tableName) {
+    const [schema, table] = splitTableName(tableName);
+    const result = await client.query(sql_template_strings_1.default `
+    SELECT EXISTS (
+      SELECT 1
+      FROM   pg_catalog.pg_class c
+      JOIN   pg_catalog.pg_namespace n 
+        ON     n.oid = c.relnamespace
+      WHERE  c.relname = ${table}
+        AND    c.relkind = 'r'
+        AND    n.nspname = ${schema}
+    );
+  `);
+    return result.rows.length > 0 && result.rows[0].exists;
+}

package/dist/migration-file.d.ts

@@ -0,0 +1,8 @@
+export declare const loadMigrationFile: (filePath: string) => Promise<{
+    id: number;
+    name: string;
+    contents: string;
+    fileName: string;
+    hash: string;
+    sql: string;
+}>;

package/dist/migration-file.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadMigrationFile = void 0;
+const util_1 = require("util");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const load_sql_from_js_1 = require("./load-sql-from-js");
+const file_name_parser_1 = require("./file-name-parser");
+const readFile = util_1.promisify(fs.readFile);
+const getFileName = (filePath) => path.basename(filePath);
+const getFileContents = async (filePath) => readFile(filePath, "utf8");
+const hashString = (s) => crypto.createHash("sha1").update(s, "utf8").digest("hex");
+const getSqlStringLiteral = (filePath, contents, type) => {
+    switch (type) {
+        case "sql":
+            return contents;
+        case "js":
+            return load_sql_from_js_1.loadSqlFromJs(filePath);
+        default: {
+            const exhaustiveCheck = type;
+            return exhaustiveCheck;
+        }
+    }
+};
+const loadMigrationFile = async (filePath) => {
+    const fileName = getFileName(filePath);
+    try {
+        const { id, name, type } = file_name_parser_1.parseFileName(fileName);
+        const contents = await getFileContents(filePath);
+        const sql = getSqlStringLiteral(filePath, contents, type);
+        const hash = hashString(fileName + sql);
+        return {
+            id,
+            name,
+            contents,
+            fileName,
+            hash,
+            sql,
+        };
+    }
+    catch (err) {
+        throw new Error(`${err.message} - Offending file: '${fileName}'.`);
+    }
+};
+exports.loadMigrationFile = loadMigrationFile;

package/dist/migrations/0_create-migrations-table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS migrations (
+  id integer PRIMARY KEY,
+  name varchar(100) UNIQUE NOT NULL,
+  hash varchar(40) NOT NULL, -- sha1 hex encoded hash of the file name and contents, to ensure it hasn't been altered since applying the migration
+  executed_at timestamp DEFAULT current_timestamp
+);

package/dist/run-migration.d.ts

@@ -0,0 +1,2 @@
+import { Logger, Migration, BasicPgClient } from "./types";
+export declare const runMigration: (migrationTableName: string, client: BasicPgClient, log?: Logger) => (migration: Migration) => Promise<Migration>;

package/dist/run-migration.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMigration = void 0;
+const sql_template_strings_1 = require("sql-template-strings");
+const noop = () => {
+    //
+};
+const insertMigration = async (migrationTableName, client, migration, log) => {
+    log(`Saving migration to '${migrationTableName}': ${migration.id} | ${migration.name} | ${migration.hash}`);
+    const sql = sql_template_strings_1.default `INSERT INTO `
+        .append(migrationTableName)
+        .append(sql_template_strings_1.default ` ("id", "name", "hash") VALUES (${migration.id},${migration.name},${migration.hash})`);
+    return client.query(sql);
+};
+const runMigration = (migrationTableName, client, log = noop) => async (migration) => {
+    const inTransaction = migration.sql.includes("-- postgres-migrations disable-transaction") ===
+        false;
+    log(`Running migration in transaction: ${inTransaction}`);
+    const begin = inTransaction ? () => client.query("START TRANSACTION") : noop;
+    const end = inTransaction ? () => client.query("COMMIT") : noop;
+    const cleanup = inTransaction ? () => client.query("ROLLBACK") : noop;
+    try {
+        await begin();
+        await client.query(migration.sql);
+        await insertMigration(migrationTableName, client, migration, log);
+        await end();
+        return migration;
+    }
+    catch (err) {
+        try {
+            await cleanup();
+        }
+        catch (_a) {
+            //
+        }
+        throw new Error(`An error occurred running '${migration.name}'. Rolled back this migration. No further migrations were run. Reason: ${err.message}`);
+    }
+};
+exports.runMigration = runMigration;

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import * as pg from "pg";
+export interface Migration {
+    readonly id: number;
+    readonly name: string;
+    readonly contents: string;
+    readonly fileName: string;
+    readonly hash: string;
+    readonly sql: string;
+}
+export interface ConnectionParams {
+    readonly user: string;
+    readonly password: string;
+    readonly host: string;
+    readonly port: number;
+}
+export interface ClientParams {
+    /** A connected Client, or a Pool Client. The caller is responsible for connecting and cleaning up. */
+    readonly client: pg.Client | pg.PoolClient | pg.Pool;
+}
+export declare type EnsureDatabase = {
+    /**
+     * Might default to `true` in future versions
+     * @default false
+     */
+    readonly ensureDatabaseExists: true;
+    /**
+     * The database to connect to when creating a database (if necessary).
+     * @default postgres
+     */
+    readonly defaultDatabase?: string;
+} | {
+    readonly ensureDatabaseExists?: false;
+};
+/**
+ * @deprecated Use `migrate` instead with `ensureDatabaseExists: true`.
+ */
+export declare type CreateDBConfig = (ConnectionParams & {
+    /** The database to connect to when creating the new database. */
+    readonly defaultDatabase?: string;
+}) | ClientParams;
+export declare type MigrateDBConfig = (ConnectionParams & {
+    readonly database: string;
+} & EnsureDatabase) | ClientParams;
+export declare type Logger = (msg: string) => void;
+export declare type Config = Partial<FullConfig>;
+export interface FullConfig {
+    readonly logger: Logger;
+    readonly schema: string;
+}
+export declare class MigrationError extends Error {
+    cause?: string;
+}
+export declare type FileType = "sql" | "js";
+export interface BasicPgClient {
+    query(queryTextOrConfig: string | pg.QueryConfig): Promise<pg.QueryResult>;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationError = void 0;
+class MigrationError extends Error {
+}
+exports.MigrationError = MigrationError;

package/dist/validation.d.ts

@@ -0,0 +1,5 @@
+import { Migration } from "./types";
+/** Assert migration IDs are consecutive integers */
+export declare function validateMigrationOrdering(migrations: Array<Migration>): void;
+/** Assert hashes match */
+export declare function validateMigrationHashes(migrations: Array<Migration>, appliedMigrations: Record<number, Migration | undefined>): void;

package/dist/validation.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateMigrationHashes = exports.validateMigrationOrdering = void 0;
+const indexNotMatch = (migration, index) => migration.id !== index;
+/** Assert migration IDs are consecutive integers */
+function validateMigrationOrdering(migrations) {
+    const notMatchingId = migrations.find(indexNotMatch);
+    if (notMatchingId) {
+        throw new Error(`Found a non-consecutive migration ID on file: '${notMatchingId.fileName}'`);
+    }
+}
+exports.validateMigrationOrdering = validateMigrationOrdering;
+/** Assert hashes match */
+function validateMigrationHashes(migrations, appliedMigrations) {
+    const invalidHash = (migration) => {
+        const appliedMigration = appliedMigrations[migration.id];
+        return appliedMigration != null && appliedMigration.hash !== migration.hash;
+    };
+    // Assert migration hashes are still same
+    const invalidHashes = migrations.filter(invalidHash);
+    if (invalidHashes.length > 0) {
+        // Someone has altered one or more migrations which has already run - gasp!
+        const invalidFiles = invalidHashes.map(({ fileName }) => fileName);
+        throw new Error(`Hashes don't match for migrations '${invalidFiles}'.
+This means that the scripts have changed since it was applied.`);
+    }
+}
+exports.validateMigrationHashes = validateMigrationHashes;

package/dist/with-connection.d.ts

@@ -0,0 +1,3 @@
+import * as pg from "pg";
+import { Logger, BasicPgClient } from "./types";
+export declare function withConnection<T>(log: Logger, f: (client: BasicPgClient) => Promise<T>): (client: pg.Client) => Promise<T>;

package/dist/with-connection.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withConnection = void 0;
+function withConnection(log, f) {
+    return async (client) => {
+        try {
+            try {
+                log("Connecting to database...");
+                await client.connect();
+                log("... connected to database");
+            }
+            catch (e) {
+                log(`Error connecting to database: ${e.message}`);
+                throw e;
+            }
+            const result = await f(client);
+            return result;
+        }
+        catch (e) {
+            log(`Error using connection: ${e.message}`);
+            throw e;
+        }
+        finally {
+            // always try to close the connection
+            try {
+                log("Closing connection...");
+                await client.end();
+                log("... connection closed");
+            }
+            catch (e) {
+                log(`Error closing the connection: ${e.message}`);
+            }
+        }
+    };
+}
+exports.withConnection = withConnection;

package/dist/with-lock.d.ts

@@ -0,0 +1,2 @@
+import { Logger, BasicPgClient } from "./types";
+export declare function withAdvisoryLock<T>(log: Logger, f: (client: BasicPgClient) => Promise<T>): (client: BasicPgClient) => Promise<T>;

package/dist/with-lock.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAdvisoryLock = void 0;
+function withAdvisoryLock(log, f) {
+    return async (client) => {
+        try {
+            try {
+                log("Acquiring advisory lock...");
+                let acquired = false;
+                while (!acquired) {
+                    const lockResult = await client.query("SELECT pg_try_advisory_lock(-8525285245963000605);");
+                    if (lockResult.rows[0].pg_try_advisory_lock === true) {
+                        acquired = true;
+                    }
+                    else {
+                        await new Promise((res) => setTimeout(res, 1000));
+                    }
+                }
+                log("... acquired advisory lock");
+            }
+            catch (e) {
+                log(`Error acquiring advisory lock: ${e.message}`);
+                throw e;
+            }
+            const result = await f(client);
+            return result;
+        }
+        catch (e) {
+            log(`Error while using lock: ${e.message}`);
+            throw e;
+        }
+        finally {
+            try {
+                log("Releasing advisory lock...");
+                await client.query("SELECT pg_advisory_unlock(-8525285245963000605);");
+                log("... released advisory lock");
+            }
+            catch (e) {
+                log(`Error releasing advisory lock: ${e.message}`);
+            }
+        }
+    };
+}
+exports.withAdvisoryLock = withAdvisoryLock;

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "postgres-schema-migrations",
+  "version": "6.0.0",
+  "description": "Stack Overflow style database migrations for PostgreSQL",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "pg-validate-migrations": "./dist/bin/validate.js"
+  },
+  "authors": ["Thom Wright", "Zak Patterson"],
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "migration",
+    "migrations",
+    "sql",
+    "database",
+    "db"
+  ],
+  "homepage": "https://github.com/zakpatterson/postgres-schema-migrations#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:zakpatterson/postgres-schema-migrations.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zakpatterson/postgres-schema-migrations/issues"
+  },
+  "engines": {
+    "node": ">10.17.0"
+  },
+  "scripts": {
+    "checkPushed": "[ \"$(git rev-list --count @{upstream}..HEAD)\" -eq 0 ] || (echo You have unpushed commits && exit 1)",
+    "prepublishOnly": "npm run checkPushed && npm test && npm run build",
+    "check-formatting": "./node_modules/.bin/prettier '**/*.ts' --list-different",
+    "fix-formatting": "./node_modules/.bin/prettier '**/*.ts' --write",
+    "lint": "npm run tslint && npm run check-formatting",
+    "tslint": "tslint 'src/**/*.ts' --type-check --project tsconfig.json --format verbose",
+    "test-integration": "ava --config ava.config.integration.cjs",
+    "test-unit": "ava --config ava.config.unit.cjs",
+    "test": "npm run test-unit && npm run lint && npm run test-integration",
+    "preversion": "npm test",
+    "build": "rm -rf ./dist && rsync -a --exclude='*.ts' --exclude='__tests__' --exclude='__unit__' --prune-empty-dirs src/ dist/ && tsc --project tsconfig-build.json"
+  },
+  "husky": {
+    "hooks": {
+      "commit-msg": "node ./node_modules/fit-commit-js/lib/hook.js .git/COMMIT_EDITMSG",
+      "pre-commit": "npm run lint",
+      "pre-push": "npm test"
+    }
+  },
+  "dependencies": {
+    "pg": "^8.6.0",
+    "sql-template-strings": "^2.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^10.17.60",
+    "@types/pg": "^8.6.0",
+    "@types/sinon": "^9.0.11",
+    "ava": "^3.15.0",
+    "fit-commit-js": "^0.3.2",
+    "husky": "^3.1.0",
+    "prettier": "^2.3.1",
+    "sinon": "^9.2.4",
+    "ts-node": "^10.0.0",
+    "tslint": "^6.1.3",
+    "tslint-config-prettier": "^1.18.0",
+    "typescript": "^4.3.4",
+    "typescript-tslint-plugin": "^1.0.1"
+  }
+}

package/tsconfig-base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "plugins": [
+      {"name": "typescript-tslint-plugin"}
+    ],
+    "typeRoots": ["./typings", "./node_modules/@types"],
+    "outDir": "./dist",
+    "target": "es2017",
+    "declaration": true,
+    "module": "commonjs",
+    "lib": ["es2017"],
+    "noUnusedLocals": true,
+    "noErrorTruncation": true,
+    "pretty": true,
+    "strict": true
+  }
+}

package/tsconfig-build.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig-base.json",
+  "include": ["./src/**/*"],
+  "exclude": ["./src/**/__tests__/*", "./src/**/__integration__/*", "./src/**/__unit__/*"]
+}

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig-base.json",
+  "include": ["./src/**/*"]
+}

package/tslint.json

@@ -0,0 +1,42 @@
+{
+  "defaultSeverity": "error",
+  "extends": ["tslint:recommended", "tslint-config-prettier"],
+  "rules": {
+    "interface-name": false,
+    "object-literal-sort-keys": false,
+    "ordered-imports": false,
+    "no-unused-expression": false,
+    "only-arrow-functions": false,
+    "array-type": [true, "generic"],
+    "no-any": {
+      "severity": "warning"
+    },
+    "no-var-requires": {
+      "severity": "warning"
+    },
+    "no-console": {
+      "severity": "warning"
+    },
+    "no-switch-case-fall-through": true,
+    "callable-types": {
+      "severity": "warning"
+    },
+    "strict-boolean-expressions": [
+      true,
+      "allow-null-union",
+      "allow-undefined-union"
+    ],
+    "no-unnecessary-initializer": false,
+    "no-implicit-dependencies": [true, "dev"],
+    "no-return-await": true,
+    "no-floating-promises": true,
+    "no-string-throw": true,
+    "no-this-assignment": true,
+    "no-unnecessary-class": true,
+    "no-unsafe-finally": true,
+    "radix": true,
+    "switch-default": true,
+    "restrict-plus-operands": true,
+    "no-invalid-template-strings": true
+  }
+}