add dryRun to migrate

Author: MatthewBurstein

README.md

@@ -75,6 +75,32 @@ async function() {
 }
 ```
 
+### Config
+
+#### `logger`
+
+This will be used for all logging from `postgres-migrations`. The function will be called passing a
+string argument with each call.
+
+#### `dryRun`
+
+Setting `dryRun` to `true` will log the filenames and SQL of all transactions to be run, without running them. It validates that the file names are the appropriate format, but it does not perform any validation of the migrations themselves so they may still fail after running.
+
+The logs look like this:
+
+```
+Migrations to run:
+  1_first_migration.sql
+  2_second_migration.js
+
+CREATE TABLE first_migration_table (
+  id integer
+);
+
+ALTER TABLE first_migration_table
+  ADD second_migration_column integer;
+```
+
 ### Validating migration files
 
 Occasionally, if two people are working on the same codebase independently, they might both create a migration at the same time. For example, `5_add-table.sql` and `5_add-column.sql`. If these both get pushed, there will be a conflict.

src/__tests__/fixtures/dry-run-false/1_dry_run_false.sql

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

src/__tests__/fixtures/dry-run-no-migrations/1_dry_run_no_migrations.sql

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

src/__tests__/fixtures/dry-run-true/1_dry_run_true_first.sql

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

src/__tests__/fixtures/dry-run-true/2_dry_run_true_second.js

@@ -0,0 +1,3 @@
+module.exports.generateSql = () =>`
+ALTER TABLE dry_run_true
+  ADD new_column integer;`

src/__tests__/migrate.ts

@@ -4,6 +4,8 @@ import * as pg from "pg"
 import SQL from "sql-template-strings"
 import {createDb, migrate, MigrateDBConfig} from "../"
 import {PASSWORD, startPostgres, stopPostgres} from "./fixtures/docker-postgres"
+import * as sinon from "sinon"
+import {SinonSpy} from "sinon"
 
 const CONTAINER_NAME = "pg-migrations-test-migrate"
 
@@ -284,6 +286,119 @@ test("successful complex js migration", (t) => {
     })
 })
 
+test("with dryRun true", (t) => {
+  const logSpy = sinon.spy()
+  const databaseName = "migration-with-dryRun-true-test"
+  const dbConfig = {
+    database: databaseName,
+    user: "postgres",
+    password: PASSWORD,
+    host: "localhost",
+    port,
+  }
+
+  const expectedLog = `
+Migrations to run:
+  1_dry_run_true_first.sql
+  2_dry_run_true_second.js
+
+CREATE TABLE dry_run_true (
+  id integer
+);
+
+ALTER TABLE dry_run_true
+  ADD new_column integer;
+`
+
+  return createDb(databaseName, dbConfig)
+    .then(() => migrate(dbConfig, "src/__tests__/fixtures/empty"))
+    .then(() =>
+      migrate(dbConfig, "src/__tests__/fixtures/dry-run-true", {
+        dryRun: true,
+        logger: logSpy,
+      }),
+    )
+    .then(() => doesTableExist(dbConfig, "dry_run_true"))
+    .then((exists) => {
+      t.falsy(exists)
+      t.assert(
+        logSpy.calledWith(expectedLog),
+        `expected logger to have been called with ${expectedLog} but was called with ${allArgsForCalls(
+          logSpy,
+        )}`,
+      )
+    })
+})
+
+test("with dryRun true but no migrations to run", (t) => {
+  const logSpy = sinon.spy()
+  const databaseName = "migration-with-dryRun-no-migrations-test"
+  const dbConfig = {
+    database: databaseName,
+    user: "postgres",
+    password: PASSWORD,
+    host: "localhost",
+    port,
+  }
+
+  const expectedLog = "\nNo new migrations to run\n"
+
+  return createDb(databaseName, dbConfig)
+    .then(() =>
+      migrate(dbConfig, "src/__tests__/fixtures/dry-run-no-migrations"),
+    )
+    .then(() => doesTableExist(dbConfig, "dry_run_no_migrations"))
+    .then((exists) => {
+      t.truthy(exists)
+    })
+    .then(() =>
+      migrate(dbConfig, "src/__tests__/fixtures/dry-run-no-migrations", {
+        dryRun: true,
+        logger: logSpy,
+      }),
+    )
+    .then(() => {
+      t.assert(
+        logSpy.calledWith(expectedLog),
+        `expected logger to have been called with ${expectedLog} but was called with ${allArgsForCalls(
+          logSpy,
+        )}`,
+      )
+    })
+})
+
+test("with dryRun false", (t) => {
+  const logSpy = sinon.spy()
+  const databaseName = "migration-with-dryRun-false-test"
+  const dbConfig = {
+    database: databaseName,
+    user: "postgres",
+    password: PASSWORD,
+    host: "localhost",
+    port,
+  }
+
+  const unexpectedLog = "CREATE TABLE dry_run_false"
+
+  return createDb(databaseName, dbConfig)
+    .then(() =>
+      migrate(dbConfig, "src/__tests__/fixtures/dry-run-false", {
+        dryRun: false,
+        logger: logSpy,
+      }),
+    )
+    .then(() => doesTableExist(dbConfig, "dry_run_false"))
+    .then((exists) => {
+      t.truthy(exists)
+      t.assert(
+        logSpy.neverCalledWithMatch(unexpectedLog),
+        `expected logger not to be called with string matching ${unexpectedLog} but was called with ${allArgsForCalls(
+          logSpy,
+        )}`,
+      )
+    })
+})
+
 test("bad arguments - no db config", (t) => {
   // tslint:disable-next-line no-any
   return t.throwsAsync((migrate as any)()).then((err) => {
@@ -720,3 +835,10 @@ function doesTableExist(dbConfig: pg.ClientConfig, tableName: string) {
       }
     })
 }
+
+function allArgsForCalls(spy: SinonSpy) {
+  return spy
+    .getCalls()
+    .map((call) => call.args)
+    .join(" | ")
+}

src/migrate.ts

@@ -38,6 +38,8 @@ export async function migrate(
           //
         }
 
+  const dryRun = config.dryRun === undefined ? false : config.dryRun
+
   if (dbConfig == null) {
     throw new Error("No config object")
   }
@@ -51,7 +53,7 @@ export async function migrate(
     // we have been given a client to use, it should already be connected
     return withAdvisoryLock(
       log,
-      runMigrations(intendedMigrations, log),
+      runMigrations(intendedMigrations, log, dryRun),
     )(dbConfig.client)
   }
 
@@ -99,15 +101,19 @@ export async function migrate(
 
     const runWith = withConnection(
       log,
-      withAdvisoryLock(log, runMigrations(intendedMigrations, log)),
+      withAdvisoryLock(log, runMigrations(intendedMigrations, log, dryRun)),
     )
 
     return runWith(client)
   }
 }
 
-function runMigrations(intendedMigrations: Array<Migration>, log: Logger) {
-  return async (client: BasicPgClient) => {
+function runMigrations(
+  intendedMigrations: Array<Migration>,
+  log: Logger,
+  dryRun: boolean,
+) {
+  return async (client: BasicPgClient): Promise<Array<Migration>> => {
     try {
       const migrationTableName = "migrations"
 
@@ -125,7 +131,12 @@ function runMigrations(intendedMigrations: Array<Migration>, log: Logger) {
         intendedMigrations,
         appliedMigrations,
       )
-      const completedMigrations = []
+      const completedMigrations: Array<Migration> = []
+
+      if (dryRun) {
+        logDryRun(migrationsToRun, log)
+        return completedMigrations
+      }
 
       for (const migration of migrationsToRun) {
         log(`Starting migration: ${migration.id} ${migration.name}`)
@@ -211,3 +222,18 @@ async function doesTableExist(client: BasicPgClient, tableName: string) {
 
   return result.rows.length > 0 && result.rows[0].exists
 }
+
+function logDryRun(migrations: Array<Migration>, log: Logger) {
+  if (migrations.length === 0) {
+    log("\nNo new migrations to run\n")
+  } else {
+    const logString =
+      "\nMigrations to run:\n" +
+      migrations.map((m) => `  ${m.fileName}`).join("\n") +
+      "\n\n" +
+      migrations.map((m) => m.sql.trim()).join("\n\n") +
+      "\n"
+
+    log(logString)
+  }
+}

src/types.ts

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