Implement custom migration table name

Use most content of PR
ThomWright#48

Author: totakoko

README.md

@@ -85,6 +85,24 @@ The `loadMigrationFiles` function can be used to check if the migration files sa
 
 Alternatively, use the `pg-validate-migrations` bin script: `pg-validate-migrations "path/to/migration/files"`.
 
+You can pass a custom migration table name:
+
+```typescript
+await migrate(dbConfig, "path/to/migration/files", {
+  migrationTableName: "my_migrations",
+})
+```
+
+This could, alternatively, be a table in an existing schema:
+
+```typescript
+await createDb(databaseName, {client})
+await client.query("CREATE SCHEMA IF NOT EXISTS my_schema")
+await migrate(dbConfig, "path/to/migration/files", {
+  migrationTableName: "my_schema.migrations",
+})
+```
+
 ## Design decisions
 
 ### No down migrations

src/__tests__/fixtures/success-existing-db/migrations/1_success.sql

@@ -0,0 +1,3 @@
+CREATE TABLE success (
+  id integer
+);

src/__tests__/fixtures/success-existing-db/restore.sql.js

@@ -0,0 +1,10 @@
+module.exports = `
+CREATE TABLE migrations (
+    id integer PRIMARY KEY,
+    name character varying(100) NOT NULL UNIQUE,
+    hash character varying(40) NOT NULL,
+    executed_at timestamp without time zone DEFAULT CURRENT_TIMESTAMP
+);
+INSERT INTO migrations ("id","name","hash","executed_at")
+VALUES (0,E'create-migrations-table',E'e18db593bcde2aca2a408c4d1100f6abba2195df',E'2020-06-29 18:38:05.064546');
+`

src/__tests__/migrate.ts

@@ -190,6 +190,61 @@ test("with pool client", async (t) => {
   }
 })
 
+test("with custom migration table name", async (t) => {
+  const databaseName = "migration-test-custom-migration-table"
+  const dbConfig = {
+    database: databaseName,
+    user: "postgres",
+    password: PASSWORD,
+    host: "localhost",
+    port,
+  }
+
+  const migrateWithCustomMigrationTable = () =>
+    migrate(dbConfig, "src/__tests__/fixtures/success-first", {
+      migrationTableName: "my_migrations",
+    })
+
+  await createDb(databaseName, dbConfig)
+  await migrateWithCustomMigrationTable()
+
+  t.truthy(await doesTableExist(dbConfig, "my_migrations"))
+  t.truthy(await doesTableExist(dbConfig, "success"))
+
+  await migrateWithCustomMigrationTable()
+})
+
+test("with custom migration table name in a custom schema", async (t) => {
+  const databaseName = "migration-test-custom-schema-custom-migration-table"
+  const dbConfig = {
+    database: databaseName,
+    user: "postgres",
+    password: PASSWORD,
+    host: "localhost",
+    port,
+  }
+
+  const migrateWithCustomMigrationTable = () =>
+    migrate(dbConfig, "src/__tests__/fixtures/success-first", {
+      migrationTableName: "my_schema.my_migrations",
+    })
+
+  const pool = new pg.Pool(dbConfig)
+
+  try {
+    await createDb(databaseName, dbConfig)
+    await pool.query("CREATE SCHEMA IF NOT EXISTS my_schema")
+    await migrateWithCustomMigrationTable()
+
+    t.truthy(await doesTableExist(dbConfig, "my_schema.my_migrations"))
+    t.truthy(await doesTableExist(dbConfig, "success"))
+
+    await migrateWithCustomMigrationTable()
+  } finally {
+    await pool.end()
+  }
+})
+
 test("successful first migration", (t) => {
   const databaseName = "migration-test-success-first"
   const dbConfig = {
@@ -284,6 +339,31 @@ test("successful complex js migration", (t) => {
     })
 })
 
+test("successful migration on an existing database", async (t) => {
+  const databaseName = "migration-test-success-existing-db"
+  const dbConfig = {
+    database: databaseName,
+    user: "postgres",
+    password: PASSWORD,
+    host: "localhost",
+    port,
+  }
+
+  const pool = new pg.Pool(dbConfig)
+
+  try {
+    await createDb(databaseName, dbConfig)
+    await pool.query(require("./fixtures/success-existing-db/restore.sql"))
+    await migrate(
+      dbConfig,
+      "src/__tests__/fixtures/success-existing-db/migrations",
+    )
+    t.truthy(await doesTableExist(dbConfig, "success"))
+  } finally {
+    await pool.end()
+  }
+})
+
 test("bad arguments - no db config", (t) => {
   // tslint:disable-next-line no-any
   return t.throwsAsync((migrate as any)()).then((err) => {
@@ -695,28 +775,27 @@ function doesTableExist(dbConfig: pg.ClientConfig, tableName: string) {
     .connect()
     .then(() =>
       client.query(SQL`
-        SELECT EXISTS (
-          SELECT 1
-          FROM   pg_catalog.pg_class c
-          WHERE  c.relname = ${tableName}
-          AND    c.relkind = 'r'
-        );
+        SELECT to_regclass(${tableName}) as matching_tables
       `),
     )
     .then((result) => {
       try {
         return client
           .end()
           .then(() => {
-            return result.rows.length > 0 && result.rows[0].exists
+            return (
+              result.rows.length > 0 && result.rows[0].matching_tables !== null
+            )
           })
           .catch((error) => {
             console.log("Async error in 'doesTableExist", error)
-            return result.rows.length > 0 && result.rows[0].exists
+            return (
+              result.rows.length > 0 && result.rows[0].matching_tables !== null
+            )
           })
       } catch (error) {
         console.log("Sync error in 'doesTableExist", error)
-        return result.rows.length > 0 && result.rows[0].exists
+        return result.rows.length > 0 && result.rows[0].matching_tables !== null
       }
     })
 }

src/__unit__/migration-file-validation/validate.ts

@@ -9,6 +9,8 @@ test("two migrations with the same id", async (t) => {
   const error = await t.throwsAsync(async () =>
     loadMigrationFiles(
       "src/__unit__/migration-file-validation/fixtures/conflict",
+      () => {}, // tslint:disable-line no-empty
+      "migrations",
     ),
   )
   t.regex(error.message, /non-consecutive/)

src/bin/validate.ts

@@ -6,8 +6,13 @@ import {loadMigrationFiles} from "../files-loader"
 
 async function main(args: Array<string>) {
   const directory = args[0]
+  const migrationTableName = args[1] ?? "migrations"
 
-  await loadMigrationFiles(directory, (x) => console.error(x))
+  await loadMigrationFiles(
+    directory,
+    (x) => console.error(x),
+    migrationTableName,
+  )
 }
 
 main(argv.slice(2)).catch((e) => {

src/files-loader.ts

@@ -1,6 +1,7 @@
 import * as fs from "fs"
 import * as path from "path"
 import {promisify} from "util"
+import {loadInitialMigration} from "./initial-migration"
 import {loadMigrationFile} from "./migration-file"
 import {Logger, Migration} from "./types"
 import {validateMigrationOrdering} from "./validation"
@@ -21,6 +22,7 @@ export const loadMigrationFiles = async (
   directory: string,
   // tslint:disable-next-line no-empty
   log: Logger = () => {},
+  migrationTableName: string,
 ): Promise<Array<Migration>> => {
   log(`Loading migrations from: ${directory}`)
 
@@ -31,17 +33,20 @@ export const loadMigrationFiles = async (
     return []
   }
 
-  const migrationFiles = [
-    path.join(__dirname, "migrations/0_create-migrations-table.sql"),
-    ...fileNames.map((fileName) => path.resolve(directory, fileName)),
-  ].filter(isValidFile)
+  const migrationFiles = fileNames
+    .map((fileName) => path.resolve(directory, fileName))
+    .filter(isValidFile)
 
   const unorderedMigrations = await Promise.all(
     migrationFiles.map(loadMigrationFile),
   )
 
+  const initialMigration = await loadInitialMigration(migrationTableName)
+
   // Arrange in ID order
-  const orderedMigrations = unorderedMigrations.sort((a, b) => a.id - b.id)
+  const orderedMigrations = [initialMigration, ...unorderedMigrations].sort(
+    (a, b) => a.id - b.id,
+  )
 
   validateMigrationOrdering(orderedMigrations)
 

src/initial-migration.ts

@@ -0,0 +1,29 @@
+import {hashString} from "./migration-file"
+
+export const loadInitialMigration = async (migrationTableName: string) => {
+  // Since the hash of the initial migration is distributed across users' databases
+  // the values `fileName` and `sql` must NEVER change!
+  const fileName = "0_create-migrations-table.sql"
+  const sql = getInitialMigrationSql(migrationTableName)
+  const hash = hashString(fileName + sql)
+
+  return {
+    id: 0,
+    name: "create-migrations-table",
+    contents: sql,
+    fileName,
+    hash,
+    sql,
+  }
+}
+
+// Formatting must not change to ensure content hash remains the same
+export const getInitialMigrationSql = (
+  migrationTableName: string,
+) => `CREATE TABLE IF NOT EXISTS ${migrationTableName} (
+  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
+);
+`

src/migrate.ts

@@ -38,20 +38,26 @@ export async function migrate(
           //
         }
 
+  const migrationTableName = config.migrationTableName ?? "migrations"
+
   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 loadMigrationFiles(migrationsDirectory, log)
+  const intendedMigrations = await loadMigrationFiles(
+    migrationsDirectory,
+    log,
+    migrationTableName,
+  )
 
   if ("client" in dbConfig) {
     // we have been given a client to use, it should already be connected
     return withAdvisoryLock(
       log,
-      runMigrations(intendedMigrations, log),
+      runMigrations(intendedMigrations, log, migrationTableName),
     )(dbConfig.client)
   }
 
@@ -99,18 +105,23 @@ export async function migrate(
 
     const runWith = withConnection(
       log,
-      withAdvisoryLock(log, runMigrations(intendedMigrations, log)),
+      withAdvisoryLock(
+        log,
+        runMigrations(intendedMigrations, log, migrationTableName),
+      ),
     )
 
     return runWith(client)
   }
 }
 
-function runMigrations(intendedMigrations: Array<Migration>, log: Logger) {
+function runMigrations(
+  intendedMigrations: Array<Migration>,
+  log: Logger,
+  migrationTableName: string,
+) {
   return async (client: BasicPgClient) => {
     try {
-      const migrationTableName = "migrations"
-
       log("Starting migrations")
 
       const appliedMigrations = await fetchAppliedMigrationFromDB(
@@ -202,12 +213,9 @@ function logResult(completedMigrations: Array<Migration>, log: Logger) {
 
 /** Check whether table exists in postgres - http://stackoverflow.com/a/24089729 */
 async function doesTableExist(client: BasicPgClient, tableName: string) {
-  const result = await client.query(SQL`SELECT EXISTS (
-  SELECT 1
-  FROM   pg_catalog.pg_class c
-  WHERE  c.relname = ${tableName}
-  AND    c.relkind = 'r'
-);`)
-
-  return result.rows.length > 0 && result.rows[0].exists
+  const result = await client.query(SQL`
+    SELECT to_regclass(${tableName}) as matching_tables;
+  `)
+
+  return result.rows.length > 0 && result.rows[0].matching_tables !== null
 }

src/migration-file.ts

@@ -11,7 +11,7 @@ const getFileName = (filePath: string) => path.basename(filePath)
 
 const getFileContents = async (filePath: string) => readFile(filePath, "utf8")
 
-const hashString = (s: string) =>
+export const hashString = (s: string) =>
   crypto.createHash("sha1").update(s, "utf8").digest("hex")
 
 const getSqlStringLiteral = (

src/types.ts

@@ -59,6 +59,7 @@ export type Config = Partial<FullConfig>
 
 export interface FullConfig {
   readonly logger: Logger
+  readonly migrationTableName: string
 }
 
 export class MigrationError extends Error {