@prairielearn/migrations 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export declare function init(migrationDir: string, project: string): Promise<void>;
+interface MigrationFile {
+    filename: string;
+    timestamp: string;
+}
+export declare function readAndValidateMigrationsFromDirectory(dir: string): Promise<MigrationFile[]>;
+export declare function sortMigrationFiles(migrationFiles: MigrationFile[]): MigrationFile[];
+export declare function getMigrationsToExecute(migrationFiles: MigrationFile[], executedMigrations: {
+    timestamp: string | null;
+}[]): MigrationFile[];
+export {};

package/dist/index.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMigrationsToExecute = exports.sortMigrationFiles = exports.readAndValidateMigrationsFromDirectory = exports.init = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const namedLocks = __importStar(require("@prairielearn/named-locks"));
+const logger_1 = require("@prairielearn/logger");
+const sqldb = __importStar(require("@prairielearn/postgres"));
+const error = __importStar(require("@prairielearn/error"));
+const sql = sqldb.loadSqlEquiv(__filename);
+async function init(migrationDir, project) {
+    const lockName = 'migrations';
+    logger_1.logger.verbose(`Waiting for lock ${lockName}`);
+    await namedLocks.doWithLock(lockName, {}, async () => {
+        logger_1.logger.verbose(`Acquired lock ${lockName}`);
+        await initWithLock(migrationDir, project);
+    });
+    logger_1.logger.verbose(`Released lock ${lockName}`);
+}
+exports.init = init;
+/**
+ * Timestamp prefixes will be of the form `YYYYMMDDHHMMSS`, which will have 14 digits.
+ * If this code is still around in the year 10000... good luck.
+ */
+const MIGRATION_FILENAME_REGEX = /^([0-9]{14})_.+\.sql$/;
+async function readAndValidateMigrationsFromDirectory(dir) {
+    const migrationFiles = (await fs_extra_1.default.readdir(dir)).filter((m) => m.endsWith('.sql'));
+    const migrations = migrationFiles.map((mf) => {
+        const match = mf.match(MIGRATION_FILENAME_REGEX);
+        if (!match) {
+            throw new Error(`Invalid migration filename: ${mf}`);
+        }
+        const timestamp = match[1] ?? null;
+        if (timestamp === null) {
+            throw new Error(`Migration ${mf} does not have a timestamp`);
+        }
+        return {
+            filename: mf,
+            timestamp,
+        };
+    });
+    // First pass: validate that all migrations have a unique timestamp prefix.
+    // This will avoid data loss and conflicts in unexpected scenarios.
+    let seenTimestamps = new Set();
+    for (const migration of migrations) {
+        const { filename, timestamp } = migration;
+        if (timestamp !== null) {
+            if (seenTimestamps.has(timestamp)) {
+                throw new Error(`Duplicate migration timestamp: ${timestamp} (${filename})`);
+            }
+            seenTimestamps.add(timestamp);
+        }
+    }
+    return migrations;
+}
+exports.readAndValidateMigrationsFromDirectory = readAndValidateMigrationsFromDirectory;
+function sortMigrationFiles(migrationFiles) {
+    return migrationFiles.sort((a, b) => {
+        return a.timestamp.localeCompare(b.timestamp);
+    });
+}
+exports.sortMigrationFiles = sortMigrationFiles;
+function getMigrationsToExecute(migrationFiles, executedMigrations) {
+    // If no migrations have ever been run, run them all.
+    if (executedMigrations.length === 0) {
+        return migrationFiles;
+    }
+    const executedMigrationTimestamps = new Set(executedMigrations.map((m) => m.timestamp));
+    return migrationFiles.filter((m) => !executedMigrationTimestamps.has(m.timestamp));
+}
+exports.getMigrationsToExecute = getMigrationsToExecute;
+async function initWithLock(migrationDir, project) {
+    logger_1.logger.verbose('Starting DB schema migration');
+    // Create the migrations table if needed
+    await sqldb.queryAsync(sql.create_migrations_table, {});
+    // Apply necessary changes to the migrations table as needed.
+    try {
+        await sqldb.queryAsync('SELECT project FROM migrations;', {});
+    }
+    catch (err) {
+        if (err.routine === 'errorMissingColumn') {
+            logger_1.logger.info('Altering migrations table');
+            await sqldb.queryAsync(sql.add_projects_column, {});
+        }
+        else {
+            throw err;
+        }
+    }
+    try {
+        await sqldb.queryAsync('SELECT timestamp FROM migrations;', {});
+    }
+    catch (err) {
+        if (err.routine === 'errorMissingColumn') {
+            logger_1.logger.info('Altering migrations table again');
+            await sqldb.queryAsync(sql.add_timestamp_column, {});
+        }
+        else {
+            throw err;
+        }
+    }
+    let allMigrations = await sqldb.queryAsync(sql.get_migrations, { project });
+    const migrationFiles = await readAndValidateMigrationsFromDirectory(migrationDir);
+    // Validation: if we not all previously-executed migrations have timestamps,
+    // prompt the user to deploy an earlier version that includes both indexes
+    // and timestamps.
+    const migrationsMissingTimestamps = allMigrations.rows.filter((m) => !m.timestamp);
+    if (migrationsMissingTimestamps.length > 0) {
+        throw new Error([
+            'The following migrations are missing timestamps:',
+            migrationsMissingTimestamps.map((m) => `  ${m.filename}`),
+            // This revision was the most recent commit to `master` before the
+            // code handling indexes was removed.
+            'You must deploy revision 1aa43c7348fa24cf636413d720d06a2fa9e38ef2 first.',
+        ].join('\n'));
+    }
+    // Refetch the list of migrations from the database.
+    allMigrations = await sqldb.queryAsync(sql.get_migrations, { project });
+    // Sort the migration files into execution order.
+    const sortedMigrationFiles = sortMigrationFiles(migrationFiles);
+    // Figure out which migrations have to be applied.
+    const migrationsToExecute = getMigrationsToExecute(sortedMigrationFiles, allMigrations.rows);
+    for (const { filename, timestamp } of migrationsToExecute) {
+        if (allMigrations.rows.length === 0) {
+            // if we are running all the migrations then log at a lower level
+            logger_1.logger.verbose(`Running migration ${filename}`);
+        }
+        else {
+            logger_1.logger.info(`Running migration ${filename}`);
+        }
+        // Read the migration.
+        const migrationSql = await fs_extra_1.default.readFile(path_1.default.join(migrationDir, filename), 'utf8');
+        // Perform the migration.
+        try {
+            await sqldb.queryAsync(migrationSql, {});
+        }
+        catch (err) {
+            error.addData(err, { sqlFile: filename });
+            throw err;
+        }
+        // Record the migration.
+        await sqldb.queryAsync(sql.insert_migration, {
+            filename: filename,
+            timestamp,
+            project,
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wDAA0B;AAC1B,gDAAwB;AAExB,sEAAwD;AACxD,iDAA8C;AAC9C,8DAAgD;AAChD,2DAA6C;AAE7C,MAAM,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;AAEpC,KAAK,UAAU,IAAI,CAAC,YAAoB,EAAE,OAAe;IAC9D,MAAM,QAAQ,GAAG,YAAY,CAAC;IAC9B,eAAM,CAAC,OAAO,CAAC,oBAAoB,QAAQ,EAAE,CAAC,CAAC;IAC/C,MAAM,UAAU,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,IAAI,EAAE;QACnD,eAAM,CAAC,OAAO,CAAC,iBAAiB,QAAQ,EAAE,CAAC,CAAC;QAC5C,MAAM,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IACH,eAAM,CAAC,OAAO,CAAC,iBAAiB,QAAQ,EAAE,CAAC,CAAC;AAC9C,CAAC;AARD,oBAQC;AAED;;;GAGG;AACH,MAAM,wBAAwB,GAAG,uBAAuB,CAAC;AAOlD,KAAK,UAAU,sCAAsC,CAC1D,GAAW;IAEX,MAAM,cAAc,GAAG,CAAC,MAAM,kBAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAEjF,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;QAC3C,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAEjD,IAAI,CAAC,KAAK,EAAE;YACV,MAAM,IAAI,KAAK,CAAC,+BAA+B,EAAE,EAAE,CAAC,CAAC;SACtD;QAED,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAEnC,IAAI,SAAS,KAAK,IAAI,EAAE;YACtB,MAAM,IAAI,KAAK,CAAC,aAAa,EAAE,4BAA4B,CAAC,CAAC;SAC9D;QAED,OAAO;YACL,QAAQ,EAAE,EAAE;YACZ,SAAS;SACV,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,mEAAmE;IACnE,IAAI,cAAc,GAAG,IAAI,GAAG,EAAE,CAAC;IAC/B,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE;QAClC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;QAE1C,IAAI,SAAS,KAAK,IAAI,EAAE;YACtB,IAAI,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;gBACjC,MAAM,IAAI,KAAK,CAAC,kCAAkC,SAAS,KAAK,QAAQ,GAAG,CAAC,CAAC;aAC9E;YACD,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;SAC/B;KACF;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAvCD,wFAuCC;AAED,SAAgB,kBAAkB,CAAC,cAA+B;IAChE,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClC,OAAO,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;AACL,CAAC;AAJD,gDAIC;AAED,SAAgB,sBAAsB,CACpC,cAA+B,EAC/B,kBAAkD;IAElD,qDAAqD;IACrD,IAAI,kBAAkB,CAAC,MAAM,KAAK,CAAC,EAAE;QACnC,OAAO,cAAc,CAAC;KACvB;IAED,MAAM,2BAA2B,GAAG,IAAI,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACxF,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,2BAA2B,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AACrF,CAAC;AAXD,wDAWC;AAED,KAAK,UAAU,YAAY,CAAC,YAAoB,EAAE,OAAe;IAC/D,eAAM,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAE/C,wCAAwC;IACxC,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAExD,6DAA6D;IAC7D,IAAI;QACF,MAAM,KAAK,CAAC,UAAU,CAAC,iCAAiC,EAAE,EAAE,CAAC,CAAC;KAC/D;IAAC,OAAO,GAAQ,EAAE;QACjB,IAAI,GAAG,CAAC,OAAO,KAAK,oBAAoB,EAAE;YACxC,eAAM,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YACzC,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;SACrD;aAAM;YACL,MAAM,GAAG,CAAC;SACX;KACF;IACD,IAAI;QACF,MAAM,KAAK,CAAC,UAAU,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC;KACjE;IAAC,OAAO,GAAQ,EAAE;QACjB,IAAI,GAAG,CAAC,OAAO,KAAK,oBAAoB,EAAE;YACxC,eAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;YAC/C,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;SACtD;aAAM;YACL,MAAM,GAAG,CAAC;SACX;KACF;IAED,IAAI,aAAa,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAE5E,MAAM,cAAc,GAAG,MAAM,sCAAsC,CAAC,YAAY,CAAC,CAAC;IAElF,4EAA4E;IAC5E,0EAA0E;IAC1E,kBAAkB;IAClB,MAAM,2BAA2B,GAAG,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACnF,IAAI,2BAA2B,CAAC,MAAM,GAAG,CAAC,EAAE;QAC1C,MAAM,IAAI,KAAK,CACb;YACE,kDAAkD;YAClD,2BAA2B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC;YACzD,kEAAkE;YAClE,qCAAqC;YACrC,0EAA0E;SAC3E,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;KACH;IAED,oDAAoD;IACpD,aAAa,GAAG,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAExE,iDAAiD;IACjD,MAAM,oBAAoB,GAAG,kBAAkB,CAAC,cAAc,CAAC,CAAC;IAEhE,kDAAkD;IAClD,MAAM,mBAAmB,GAAG,sBAAsB,CAAC,oBAAoB,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC;IAE7F,KAAK,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,mBAAmB,EAAE;QACzD,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;YACnC,iEAAiE;YACjE,eAAM,CAAC,OAAO,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;SACjD;aAAM;YACL,eAAM,CAAC,IAAI,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;SAC9C;QAED,sBAAsB;QACtB,MAAM,YAAY,GAAG,MAAM,kBAAE,CAAC,QAAQ,CAAC,cAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QAElF,yBAAyB;QACzB,IAAI;YACF,MAAM,KAAK,CAAC,UAAU,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;SAC1C;QAAC,OAAO,GAAG,EAAE;YACZ,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC1C,MAAM,GAAG,CAAC;SACX;QAED,wBAAwB;QACxB,MAAM,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,gBAAgB,EAAE;YAC3C,QAAQ,EAAE,QAAQ;YAClB,SAAS;YACT,OAAO;SACR,CAAC,CAAC;KACJ;AACH,CAAC"}

package/dist/index.sql

@@ -0,0 +1,61 @@
+-- BLOCK create_migrations_table
+CREATE TABLE IF NOT EXISTS
+  migrations (
+    id BIGSERIAL PRIMARY KEY,
+    filename TEXT,
+    index INTEGER,
+    project TEXT DEFAULT 'prairielearn',
+    applied_at TIMESTAMP WITH TIME ZONE,
+    timestamp TEXT,
+    UNIQUE (project, index),
+    UNIQUE (project, timestamp)
+  );
+
+-- BLOCK add_projects_column
+ALTER TABLE migrations
+ADD COLUMN IF NOT EXISTS project TEXT DEFAULT 'prairielearn';
+
+CREATE UNIQUE INDEX IF NOT EXISTS migrations_project_index_key ON migrations (index, project);
+
+ALTER TABLE migrations
+DROP CONSTRAINT migrations_index_key;
+
+DROP INDEX IF EXISTS migrations_index_key;
+
+-- BLOCK add_timestamp_column
+ALTER TABLE migrations
+ADD COLUMN IF NOT EXISTS timestamp TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS migrations_project_timestamp_key ON migrations (timestamp, project);
+
+-- BLOCK get_migrations
+SELECT
+  id,
+  filename,
+  index,
+  timestamp
+FROM
+  migrations
+WHERE
+  project = $project;
+
+-- BLOCK update_migration
+UPDATE migrations
+SET
+  filename = $filename,
+  timestamp = $timestamp
+WHERE
+  id = $id;
+
+-- BLOCK insert_migration
+INSERT INTO
+  migrations (filename, timestamp, project, applied_at)
+VALUES
+  (
+    $filename::TEXT,
+    $timestamp,
+    $project,
+    CURRENT_TIMESTAMP
+  )
+RETURNING
+  id;

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,127 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = __importStar(require("chai"));
+const chai_as_promised_1 = __importDefault(require("chai-as-promised"));
+const path_1 = __importDefault(require("path"));
+const tmp_promise_1 = __importDefault(require("tmp-promise"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const index_1 = require("./index");
+chai_1.default.use(chai_as_promised_1.default);
+async function withMigrationFiles(files, fn) {
+    await tmp_promise_1.default.withDir(async function (tmpDir) {
+        for (const file of files) {
+            await fs_extra_1.default.writeFile(path_1.default.join(tmpDir.path, file), '');
+        }
+        await fn(tmpDir.path);
+    }, { unsafeCleanup: true });
+}
+describe('migrations', () => {
+    describe('readAndValidateMigrationsFromDirectory', () => {
+        it('handles migrations without a timestamp', async () => {
+            await withMigrationFiles(['001_testing.sql'], async (tmpDir) => {
+                await chai_1.assert.isRejected((0, index_1.readAndValidateMigrationsFromDirectory)(tmpDir), 'Invalid migration filename: 001_testing.sql');
+            });
+        });
+        it('handles duplicate timestamps', async () => {
+            await withMigrationFiles(['20220101010101_testing.sql', '20220101010101_testing_again.sql'], async (tmpDir) => {
+                await chai_1.assert.isRejected((0, index_1.readAndValidateMigrationsFromDirectory)(tmpDir), 'Duplicate migration timestamp');
+            });
+        });
+    });
+    describe('sortMigrationFiles', () => {
+        it('sorts by timestamp', () => {
+            chai_1.assert.deepEqual((0, index_1.sortMigrationFiles)([
+                {
+                    filename: '20220101010103_testing_3.sql',
+                    timestamp: '20220101010103',
+                },
+                {
+                    filename: '20220101010101_testing_1.sql',
+                    timestamp: '20220101010101',
+                },
+                {
+                    filename: '20220101010102_testing_2.sql',
+                    timestamp: '20220101010102',
+                },
+            ]), [
+                {
+                    filename: '20220101010101_testing_1.sql',
+                    timestamp: '20220101010101',
+                },
+                {
+                    filename: '20220101010102_testing_2.sql',
+                    timestamp: '20220101010102',
+                },
+                {
+                    filename: '20220101010103_testing_3.sql',
+                    timestamp: '20220101010103',
+                },
+            ]);
+        });
+    });
+    describe('getMigrationsToExecute', () => {
+        it('handles the case of no executed migrations', () => {
+            const migrationFiles = [
+                {
+                    filename: '001_testing.sql',
+                    timestamp: '20220101010101',
+                },
+            ];
+            chai_1.assert.deepEqual((0, index_1.getMigrationsToExecute)(migrationFiles, []), migrationFiles);
+        });
+        it('handles case where subset of migrations have been executed', () => {
+            const migrationFiles = [
+                {
+                    filename: '20220101010101_testing_1.sql',
+                    timestamp: '20220101010101',
+                },
+                {
+                    filename: '20220101010102_testing_2.sql',
+                    timestamp: '20220101010102',
+                },
+                {
+                    filename: '20220101010103_testing_3.sql',
+                    timestamp: '20220101010103',
+                },
+            ];
+            const executedMigrations = [
+                {
+                    timestamp: '20220101010101',
+                },
+                {
+                    timestamp: '20220101010102',
+                },
+            ];
+            chai_1.assert.deepEqual((0, index_1.getMigrationsToExecute)(migrationFiles, executedMigrations), [
+                { timestamp: '20220101010103', filename: '20220101010103_testing_3.sql' },
+            ]);
+        });
+    });
+});
+//# sourceMappingURL=index.test.js.map

package/dist/index.test.js.map

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

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@prairielearn/migrations",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc && copyfiles -u 1 \"./src/**/*.sql\" dist",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "test": "mocha --no-config --require ts-node/register src/*.test.ts"
+  },
+  "devDependencies": {
+    "@prairielearn/tsconfig": "*",
+    "@types/fs-extra": "^11.0.1",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^18.14.2",
+    "copyfiles": "^2.4.1",
+    "mocha": "^10.2.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "@prairielearn/error": "^1.0.0",
+    "@prairielearn/named-locks": "^1.0.0",
+    "@prairielearn/postgres": "^1.2.0",
+    "fs-extra": "^11.1.0"
+  }
+}

package/src/index.sql

@@ -0,0 +1,61 @@
+-- BLOCK create_migrations_table
+CREATE TABLE IF NOT EXISTS
+  migrations (
+    id BIGSERIAL PRIMARY KEY,
+    filename TEXT,
+    index INTEGER,
+    project TEXT DEFAULT 'prairielearn',
+    applied_at TIMESTAMP WITH TIME ZONE,
+    timestamp TEXT,
+    UNIQUE (project, index),
+    UNIQUE (project, timestamp)
+  );
+
+-- BLOCK add_projects_column
+ALTER TABLE migrations
+ADD COLUMN IF NOT EXISTS project TEXT DEFAULT 'prairielearn';
+
+CREATE UNIQUE INDEX IF NOT EXISTS migrations_project_index_key ON migrations (index, project);
+
+ALTER TABLE migrations
+DROP CONSTRAINT migrations_index_key;
+
+DROP INDEX IF EXISTS migrations_index_key;
+
+-- BLOCK add_timestamp_column
+ALTER TABLE migrations
+ADD COLUMN IF NOT EXISTS timestamp TEXT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS migrations_project_timestamp_key ON migrations (timestamp, project);
+
+-- BLOCK get_migrations
+SELECT
+  id,
+  filename,
+  index,
+  timestamp
+FROM
+  migrations
+WHERE
+  project = $project;
+
+-- BLOCK update_migration
+UPDATE migrations
+SET
+  filename = $filename,
+  timestamp = $timestamp
+WHERE
+  id = $id;
+
+-- BLOCK insert_migration
+INSERT INTO
+  migrations (filename, timestamp, project, applied_at)
+VALUES
+  (
+    $filename::TEXT,
+    $timestamp,
+    $project,
+    CURRENT_TIMESTAMP
+  )
+RETURNING
+  id;

package/src/index.test.ts

@@ -0,0 +1,125 @@
+import chai, { assert } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+import path from 'path';
+import tmp from 'tmp-promise';
+import fs from 'fs-extra';
+
+import {
+  readAndValidateMigrationsFromDirectory,
+  sortMigrationFiles,
+  getMigrationsToExecute,
+} from './index';
+
+chai.use(chaiAsPromised);
+
+async function withMigrationFiles(files: string[], fn: (tmpDir: string) => Promise<void>) {
+  await tmp.withDir(
+    async function (tmpDir) {
+      for (const file of files) {
+        await fs.writeFile(path.join(tmpDir.path, file), '');
+      }
+      await fn(tmpDir.path);
+    },
+    { unsafeCleanup: true }
+  );
+}
+
+describe('migrations', () => {
+  describe('readAndValidateMigrationsFromDirectory', () => {
+    it('handles migrations without a timestamp', async () => {
+      await withMigrationFiles(['001_testing.sql'], async (tmpDir) => {
+        await assert.isRejected(
+          readAndValidateMigrationsFromDirectory(tmpDir),
+          'Invalid migration filename: 001_testing.sql'
+        );
+      });
+    });
+
+    it('handles duplicate timestamps', async () => {
+      await withMigrationFiles(
+        ['20220101010101_testing.sql', '20220101010101_testing_again.sql'],
+        async (tmpDir) => {
+          await assert.isRejected(
+            readAndValidateMigrationsFromDirectory(tmpDir),
+            'Duplicate migration timestamp'
+          );
+        }
+      );
+    });
+  });
+
+  describe('sortMigrationFiles', () => {
+    it('sorts by timestamp', () => {
+      assert.deepEqual(
+        sortMigrationFiles([
+          {
+            filename: '20220101010103_testing_3.sql',
+            timestamp: '20220101010103',
+          },
+          {
+            filename: '20220101010101_testing_1.sql',
+            timestamp: '20220101010101',
+          },
+          {
+            filename: '20220101010102_testing_2.sql',
+            timestamp: '20220101010102',
+          },
+        ]),
+        [
+          {
+            filename: '20220101010101_testing_1.sql',
+            timestamp: '20220101010101',
+          },
+          {
+            filename: '20220101010102_testing_2.sql',
+            timestamp: '20220101010102',
+          },
+          {
+            filename: '20220101010103_testing_3.sql',
+            timestamp: '20220101010103',
+          },
+        ]
+      );
+    });
+  });
+
+  describe('getMigrationsToExecute', () => {
+    it('handles the case of no executed migrations', () => {
+      const migrationFiles = [
+        {
+          filename: '001_testing.sql',
+          timestamp: '20220101010101',
+        },
+      ];
+      assert.deepEqual(getMigrationsToExecute(migrationFiles, []), migrationFiles);
+    });
+
+    it('handles case where subset of migrations have been executed', () => {
+      const migrationFiles = [
+        {
+          filename: '20220101010101_testing_1.sql',
+          timestamp: '20220101010101',
+        },
+        {
+          filename: '20220101010102_testing_2.sql',
+          timestamp: '20220101010102',
+        },
+        {
+          filename: '20220101010103_testing_3.sql',
+          timestamp: '20220101010103',
+        },
+      ];
+      const executedMigrations = [
+        {
+          timestamp: '20220101010101',
+        },
+        {
+          timestamp: '20220101010102',
+        },
+      ];
+      assert.deepEqual(getMigrationsToExecute(migrationFiles, executedMigrations), [
+        { timestamp: '20220101010103', filename: '20220101010103_testing_3.sql' },
+      ]);
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,175 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+import * as namedLocks from '@prairielearn/named-locks';
+import { logger } from '@prairielearn/logger';
+import * as sqldb from '@prairielearn/postgres';
+import * as error from '@prairielearn/error';
+
+const sql = sqldb.loadSqlEquiv(__filename);
+
+export async function init(migrationDir: string, project: string) {
+  const lockName = 'migrations';
+  logger.verbose(`Waiting for lock ${lockName}`);
+  await namedLocks.doWithLock(lockName, {}, async () => {
+    logger.verbose(`Acquired lock ${lockName}`);
+    await initWithLock(migrationDir, project);
+  });
+  logger.verbose(`Released lock ${lockName}`);
+}
+
+/**
+ * Timestamp prefixes will be of the form `YYYYMMDDHHMMSS`, which will have 14 digits.
+ * If this code is still around in the year 10000... good luck.
+ */
+const MIGRATION_FILENAME_REGEX = /^([0-9]{14})_.+\.sql$/;
+
+interface MigrationFile {
+  filename: string;
+  timestamp: string;
+}
+
+export async function readAndValidateMigrationsFromDirectory(
+  dir: string
+): Promise<MigrationFile[]> {
+  const migrationFiles = (await fs.readdir(dir)).filter((m) => m.endsWith('.sql'));
+
+  const migrations = migrationFiles.map((mf) => {
+    const match = mf.match(MIGRATION_FILENAME_REGEX);
+
+    if (!match) {
+      throw new Error(`Invalid migration filename: ${mf}`);
+    }
+
+    const timestamp = match[1] ?? null;
+
+    if (timestamp === null) {
+      throw new Error(`Migration ${mf} does not have a timestamp`);
+    }
+
+    return {
+      filename: mf,
+      timestamp,
+    };
+  });
+
+  // First pass: validate that all migrations have a unique timestamp prefix.
+  // This will avoid data loss and conflicts in unexpected scenarios.
+  let seenTimestamps = new Set();
+  for (const migration of migrations) {
+    const { filename, timestamp } = migration;
+
+    if (timestamp !== null) {
+      if (seenTimestamps.has(timestamp)) {
+        throw new Error(`Duplicate migration timestamp: ${timestamp} (${filename})`);
+      }
+      seenTimestamps.add(timestamp);
+    }
+  }
+
+  return migrations;
+}
+
+export function sortMigrationFiles(migrationFiles: MigrationFile[]): MigrationFile[] {
+  return migrationFiles.sort((a, b) => {
+    return a.timestamp.localeCompare(b.timestamp);
+  });
+}
+
+export function getMigrationsToExecute(
+  migrationFiles: MigrationFile[],
+  executedMigrations: { timestamp: string | null }[]
+): MigrationFile[] {
+  // If no migrations have ever been run, run them all.
+  if (executedMigrations.length === 0) {
+    return migrationFiles;
+  }
+
+  const executedMigrationTimestamps = new Set(executedMigrations.map((m) => m.timestamp));
+  return migrationFiles.filter((m) => !executedMigrationTimestamps.has(m.timestamp));
+}
+
+async function initWithLock(migrationDir: string, project: string) {
+  logger.verbose('Starting DB schema migration');
+
+  // Create the migrations table if needed
+  await sqldb.queryAsync(sql.create_migrations_table, {});
+
+  // Apply necessary changes to the migrations table as needed.
+  try {
+    await sqldb.queryAsync('SELECT project FROM migrations;', {});
+  } catch (err: any) {
+    if (err.routine === 'errorMissingColumn') {
+      logger.info('Altering migrations table');
+      await sqldb.queryAsync(sql.add_projects_column, {});
+    } else {
+      throw err;
+    }
+  }
+  try {
+    await sqldb.queryAsync('SELECT timestamp FROM migrations;', {});
+  } catch (err: any) {
+    if (err.routine === 'errorMissingColumn') {
+      logger.info('Altering migrations table again');
+      await sqldb.queryAsync(sql.add_timestamp_column, {});
+    } else {
+      throw err;
+    }
+  }
+
+  let allMigrations = await sqldb.queryAsync(sql.get_migrations, { project });
+
+  const migrationFiles = await readAndValidateMigrationsFromDirectory(migrationDir);
+
+  // Validation: if we not all previously-executed migrations have timestamps,
+  // prompt the user to deploy an earlier version that includes both indexes
+  // and timestamps.
+  const migrationsMissingTimestamps = allMigrations.rows.filter((m) => !m.timestamp);
+  if (migrationsMissingTimestamps.length > 0) {
+    throw new Error(
+      [
+        'The following migrations are missing timestamps:',
+        migrationsMissingTimestamps.map((m) => `  ${m.filename}`),
+        // This revision was the most recent commit to `master` before the
+        // code handling indexes was removed.
+        'You must deploy revision 1aa43c7348fa24cf636413d720d06a2fa9e38ef2 first.',
+      ].join('\n')
+    );
+  }
+
+  // Refetch the list of migrations from the database.
+  allMigrations = await sqldb.queryAsync(sql.get_migrations, { project });
+
+  // Sort the migration files into execution order.
+  const sortedMigrationFiles = sortMigrationFiles(migrationFiles);
+
+  // Figure out which migrations have to be applied.
+  const migrationsToExecute = getMigrationsToExecute(sortedMigrationFiles, allMigrations.rows);
+
+  for (const { filename, timestamp } of migrationsToExecute) {
+    if (allMigrations.rows.length === 0) {
+      // if we are running all the migrations then log at a lower level
+      logger.verbose(`Running migration ${filename}`);
+    } else {
+      logger.info(`Running migration ${filename}`);
+    }
+
+    // Read the migration.
+    const migrationSql = await fs.readFile(path.join(migrationDir, filename), 'utf8');
+
+    // Perform the migration.
+    try {
+      await sqldb.queryAsync(migrationSql, {});
+    } catch (err) {
+      error.addData(err, { sqlFile: filename });
+      throw err;
+    }
+
+    // Record the migration.
+    await sqldb.queryAsync(sql.insert_migration, {
+      filename: filename,
+      timestamp,
+      project,
+    });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@prairielearn/tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node", "mocha"],
+  }
+}