stepwise-migrations 1.0.5 → 1.0.7

package/README.md

@@ -4,16 +4,49 @@
 
 A tool for managing Raw SQL migrations in a Postgres database.
 Loosely based on flyway.
-Only "up" migrations are supported so far, but what more do you need?
 
-## Notes
+## Instructions
 
-All files ending in `.sql` in the migration directory will be applied.
-They are first sorted in ascending order based on filename.
+Name up migration files as `.sql` and down migration files with the same name but suffixed with `.down.sql`.
+e.g. `v1_users.sql` and `v1_users.down.sql`.
+NOTE: Down migrations are optional.
+
+Up migrations are first sorted in ascending order based on filename.
 No subdirectories are read below the migration directory.
 
 ## Usage
 
+```
+Usage: stepwise-migrations [command] [options]
+
+Commands:
+  migrate
+    Migrate the database to the latest version
+  down
+    Rollback the database to the previous version
+  info
+    Show information about the current state of the migrations in the database
+  drop
+    Drop all tables, schema and migration history table
+
+Options:
+  --connection <connection>  The connection string to use to connect to the database
+  --schema <schema>          The schema to use for the migrations
+  --path <path>              The path to the migrations directory
+  --ssl true/false           Whether to use SSL for the connection (default: false)
+  --nup                      Number of up migrations to apply (default: all)
+  --ndown                    Number of down migrations to apply (default: 1)
+
+Example:
+  npx stepwise-migrations \
+    --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydatabase \
+    --schema=myschema \
+    --path=./db/migration/ \
+    migrate
+```
+
+## Examples
+
 ### Migrate
 
 Command:
@@ -36,8 +69,33 @@ Migration history table created
 Found 2 migration files
 Applied migration V0_01__connect_session_table.sql
 Applied migration V0_02__auth.sql
+All done!
+```
+
+### Down
+
+Command:
+
+```bash
+npx stepwise-migrations down \
+  --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
+  --schema=myschema \
+  --path=./db/migration/
+```
 
+Outputs:
+
+```
+
+Connected to the database
+Applied down migration v2_auth.down.sql
 All done!
+New migration history:
+┌─────────┬────┬────────────────────────────────┬────────────────────────────────────────────────────────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ name                           │ hash                                                               │ applied_by │ applied_at                   │
+├─────────┼────┼────────────────────────────────┼────────────────────────────────────────────────────────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 1  │ 'v1_connect_session_table.sql' │ 'f08638e58139ae0e2dda24b1bdba29f3f2128597066a23d2bb382d448bbe9d7e' │ 'postgres' │ '2024-11-23 18:13:36.518495' │
+└─────────┴────┴────────────────────────────────┴────────────────────────────────────────────────────────────────────┴────────────┴──────────────────────────────┘
 ```
 
 ### Info
@@ -78,6 +136,5 @@ Outputs:
 ```
 Connected to the database
 Dropping the tables, schema and migration history table
-
 All done!
 ```

package/dist/db.js

@@ -93,7 +93,7 @@ const dbCreateHistoryTable = (client, schema) => __awaiter(void 0, void 0, void
     console.log(`Creating migration history table`);
     yield client.query(`CREATE TABLE IF NOT EXISTS ${schema}.stepwise_migrations (
     id SERIAL PRIMARY KEY,
-    name TEXT NOT NULL,
+    name TEXT UNIQUE NOT NULL,
     hash TEXT NOT NULL,
     applied_by TEXT NOT NULL DEFAULT current_user,
     applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP

package/dist/index.js

@@ -26,6 +26,7 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
     const historySchemaExists = yield (0, db_1.dbHistorySchemaExists)(client, schema);
     const tableExists = yield (0, db_1.dbTableExists)(client, schema);
     if (command === "migrate") {
+        const nUp = argv.nup || Infinity;
         if (!historySchemaExists) {
             yield (0, db_1.dbCreateSchema)(client, schema);
         }
@@ -36,11 +37,13 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
         const migrationFiles = yield (0, utils_1.readMigrationFiles)(argv.path);
         console.log(`Found ${migrationFiles.length} migration files`);
         (0, migrate_1.validateMigrationFiles)(migrationFiles, migrationHistory);
-        const migrationsToApply = migrationFiles.slice(migrationHistory.length);
+        const migrationsToApply = migrationFiles.slice(migrationHistory.length, migrationHistory.length + nUp);
         for (const { filename, contents, hash } of migrationsToApply) {
             yield (0, migrate_1.applyMigration)(client, schema, filename, contents, hash);
         }
-        console.log("\nAll done!");
+        console.log("All done!");
+        console.log("New migration history:");
+        console.table(yield (0, db_1.dbMigrationHistory)(client, schema));
     }
     else if (command === "info") {
         console.log("Showing information about the current state of the migrations in the database");
@@ -54,7 +57,21 @@ const main = () => __awaiter(void 0, void 0, void 0, function* () {
     else if (command === "drop") {
         console.log("Dropping the tables, schema and migration history table");
         yield client.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
-        console.log("\nAll done!");
+        console.log("All done!");
+    }
+    else if (command === "down") {
+        const nDown = argv.ndown || 1;
+        const migrationHistory = yield (0, db_1.dbMigrationHistory)(client, schema);
+        (0, migrate_1.validateMigrationFiles)(yield (0, utils_1.readMigrationFiles)(argv.path), migrationHistory, false);
+        const reverseMigrationHistory = migrationHistory.reverse().slice(0, nDown);
+        const downMigrationFilesToApply = yield (0, utils_1.readDownMigrationFiles)(argv.path, reverseMigrationHistory);
+        (0, migrate_1.validateDownMigrationFiles)(downMigrationFilesToApply, reverseMigrationHistory);
+        for (const { filename, contents, upFilename, } of downMigrationFilesToApply) {
+            yield (0, migrate_1.applyDownMigration)(client, schema, filename, contents, upFilename);
+        }
+        console.log("All done!");
+        console.log("New migration history:");
+        console.table(yield (0, db_1.dbMigrationHistory)(client, schema));
     }
     client.release();
     process.exit(0);

package/dist/migrate.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyMigration = exports.validateMigrationFiles = void 0;
-const validateMigrationFiles = (migrationFiles, migrationHistory) => {
+exports.applyDownMigration = exports.validateDownMigrationFiles = exports.applyMigration = exports.validateMigrationFiles = void 0;
+const validateMigrationFiles = (migrationFiles, migrationHistory, isUp = true) => {
     if (migrationFiles.length === 0) {
         console.log("No migrations found");
         process.exit(0);
@@ -19,7 +19,7 @@ const validateMigrationFiles = (migrationFiles, migrationHistory) => {
         console.error("Error: migration history is longer than the number of migration files, aborting.");
         process.exit(1);
     }
-    if (migrationFiles.length === migrationHistory.length) {
+    if (migrationFiles.length === migrationHistory.length && isUp) {
         console.log("All migrations are already applied");
         process.exit(0);
     }
@@ -60,3 +60,35 @@ const applyMigration = (client, schema, filename, contents, hash) => __awaiter(v
     }
 });
 exports.applyMigration = applyMigration;
+const validateDownMigrationFiles = (downMigrationFilesToApply, reverseMigrationHistory) => {
+    for (let i = 0; i < downMigrationFilesToApply.length; i++) {
+        const { filename } = downMigrationFilesToApply[i];
+        if (filename.split(".down.sql")[0] !==
+            reverseMigrationHistory[i].name.split(".sql")[0]) {
+            console.error(`Migration ${filename} does not match the expected migration ${reverseMigrationHistory[i].name}`);
+            process.exit(1);
+        }
+    }
+};
+exports.validateDownMigrationFiles = validateDownMigrationFiles;
+const applyDownMigration = (client, schema, filename, contents, upFilename) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        yield client.query("BEGIN");
+        yield client.query(`SET search_path TO ${schema};
+    ${contents.toString()}`);
+        yield client.query(`DELETE FROM ${schema}.stepwise_migrations WHERE name = $1`, [upFilename]);
+        yield client.query("COMMIT");
+        console.log(`Applied down migration ${filename}`);
+    }
+    catch (error) {
+        try {
+            yield client.query("ROLLBACK");
+        }
+        catch (error) {
+            console.error("Error rolling back transaction", error);
+        }
+        console.error("Error applying down migration", error);
+        process.exit(1);
+    }
+});
+exports.applyDownMigration = applyDownMigration;

package/dist/utils.js

@@ -12,21 +12,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readMigrationFiles = exports.validateArgs = exports.usage = exports.hashFile = void 0;
+exports.readDownMigrationFiles = exports.fileExists = exports.readMigrationFiles = exports.validateArgs = exports.usage = exports.calculateHash = void 0;
 const crypto_1 = __importDefault(require("crypto"));
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const hashFile = (path) => __awaiter(void 0, void 0, void 0, function* () {
-    const file = yield promises_1.default.readFile(path);
-    return crypto_1.default.createHash("sha256").update(file).digest("hex");
-});
-exports.hashFile = hashFile;
+const calculateHash = (contents) => {
+    return crypto_1.default.createHash("sha256").update(contents).digest("hex");
+};
+exports.calculateHash = calculateHash;
 exports.usage = `
 Usage: stepwise-migrations [command] [options]
 
 Commands:
   migrate
     Migrate the database to the latest version
+  down
+    Rollback the database to the previous version
   info
     Show information about the current state of the migrations in the database
   drop
@@ -37,6 +38,8 @@ Options:
   --schema <schema>          The schema to use for the migrations
   --path <path>              The path to the migrations directory
   --ssl true/false           Whether to use SSL for the connection (default: false)
+  --nup                      Number of up migrations to apply (default: all)
+  --ndown                    Number of down migrations to apply (default: 1)
 
 Example:
   npx stepwise-migrations \
@@ -57,7 +60,10 @@ const validateArgs = (argv) => {
         console.log(exports.usage);
         process.exit(1);
     }
-    if (argv._[0] !== "migrate" && argv._[0] !== "info" && argv._[0] !== "drop") {
+    if (argv._[0] !== "migrate" &&
+        argv._[0] !== "info" &&
+        argv._[0] !== "drop" &&
+        argv._[0] !== "down") {
         console.error(`Invalid command: ${argv._[0]}`);
         console.log(exports.usage);
         process.exit(1);
@@ -67,20 +73,51 @@ exports.validateArgs = validateArgs;
 const readMigrationFiles = (directory) => __awaiter(void 0, void 0, void 0, function* () {
     const files = yield promises_1.default.readdir(directory, { withFileTypes: true });
     const migrationFiles = files
-        .filter((file) => file.isFile() && file.name.endsWith(".sql"))
+        .filter((file) => file.isFile() &&
+        file.name.endsWith(".sql") &&
+        !file.name.endsWith(".down.sql"))
         .map((file) => path_1.default.join(directory, file.name));
     migrationFiles.sort();
     const results = [];
     for (const fullFilePath of migrationFiles) {
-        const hash = yield (0, exports.hashFile)(fullFilePath);
         const contents = yield promises_1.default.readFile(fullFilePath, "utf8");
         results.push({
+            type: "up",
             fullFilePath,
             filename: path_1.default.basename(fullFilePath),
-            hash,
+            hash: (0, exports.calculateHash)(contents),
             contents,
         });
     }
     return results;
 });
 exports.readMigrationFiles = readMigrationFiles;
+const fileExists = (path) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        return (yield promises_1.default.stat(path)).isFile();
+    }
+    catch (error) {
+        return false;
+    }
+});
+exports.fileExists = fileExists;
+const readDownMigrationFiles = (directory, migrationHistory) => __awaiter(void 0, void 0, void 0, function* () {
+    const results = [];
+    for (const migration of migrationHistory) {
+        const fullFilePath = path_1.default.join(directory, `${migration.name.split(".sql")[0]}.down.sql`);
+        if (!(yield (0, exports.fileExists)(fullFilePath))) {
+            console.error(`Down migration file not found: ${fullFilePath}`);
+            process.exit(1);
+        }
+        const contents = yield promises_1.default.readFile(fullFilePath, "utf8");
+        results.push({
+            type: "down",
+            fullFilePath,
+            filename: path_1.default.basename(fullFilePath),
+            upFilename: migration.name,
+            contents,
+        });
+    }
+    return results;
+});
+exports.readDownMigrationFiles = readDownMigrationFiles;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stepwise-migrations",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "",
   "main": "index.js",
   "scripts": {

package/src/db.ts

@@ -1,4 +1,5 @@
 import pg, { Pool, PoolClient } from "pg";
+import { MigrationRow } from "./types";
 
 pg.types.setTypeParser(1114, function (stringValue) {
   return stringValue; //1114 for time without timezone type
@@ -52,7 +53,7 @@ export const dbMigrationHistory = async (
   const migrationsQuery = await client.query(
     `SELECT * FROM ${schema}.stepwise_migrations`
   );
-  return migrationsQuery.rows;
+  return migrationsQuery.rows as MigrationRow[];
 };
 
 export const dbCreateSchema = async (client: PoolClient, schema: string) => {
@@ -69,7 +70,7 @@ export const dbCreateHistoryTable = async (
   await client.query(
     `CREATE TABLE IF NOT EXISTS ${schema}.stepwise_migrations (
     id SERIAL PRIMARY KEY,
-    name TEXT NOT NULL,
+    name TEXT UNIQUE NOT NULL,
     hash TEXT NOT NULL,
     applied_by TEXT NOT NULL DEFAULT current_user,
     applied_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP

package/src/index.ts

@@ -9,8 +9,17 @@ import {
   dbMigrationHistory,
   dbTableExists,
 } from "./db";
-import { applyMigration, validateMigrationFiles } from "./migrate";
-import { readMigrationFiles, validateArgs } from "./utils";
+import {
+  applyDownMigration,
+  applyMigration,
+  validateDownMigrationFiles,
+  validateMigrationFiles,
+} from "./migrate";
+import {
+  readDownMigrationFiles,
+  readMigrationFiles,
+  validateArgs,
+} from "./utils";
 
 const main = async () => {
   const argv: any = yargs(process.argv.slice(2)).argv;
@@ -25,6 +34,7 @@ const main = async () => {
   const tableExists = await dbTableExists(client, schema);
 
   if (command === "migrate") {
+    const nUp = argv.nup || Infinity;
     if (!historySchemaExists) {
       await dbCreateSchema(client, schema);
     }
@@ -38,12 +48,18 @@ const main = async () => {
 
     validateMigrationFiles(migrationFiles, migrationHistory);
 
-    const migrationsToApply = migrationFiles.slice(migrationHistory.length);
+    const migrationsToApply = migrationFiles.slice(
+      migrationHistory.length,
+      migrationHistory.length + nUp
+    );
 
     for (const { filename, contents, hash } of migrationsToApply) {
       await applyMigration(client, schema, filename, contents, hash);
     }
-    console.log("\nAll done!");
+
+    console.log("All done!");
+    console.log("New migration history:");
+    console.table(await dbMigrationHistory(client, schema));
   } else if (command === "info") {
     console.log(
       "Showing information about the current state of the migrations in the database"
@@ -61,7 +77,37 @@ const main = async () => {
   } else if (command === "drop") {
     console.log("Dropping the tables, schema and migration history table");
     await client.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
-    console.log("\nAll done!");
+    console.log("All done!");
+  } else if (command === "down") {
+    const nDown = argv.ndown || 1;
+
+    const migrationHistory = await dbMigrationHistory(client, schema);
+    validateMigrationFiles(
+      await readMigrationFiles(argv.path),
+      migrationHistory,
+      false
+    );
+
+    const reverseMigrationHistory = migrationHistory.reverse().slice(0, nDown);
+    const downMigrationFilesToApply = await readDownMigrationFiles(
+      argv.path,
+      reverseMigrationHistory
+    );
+
+    validateDownMigrationFiles(
+      downMigrationFilesToApply,
+      reverseMigrationHistory
+    );
+    for (const {
+      filename,
+      contents,
+      upFilename,
+    } of downMigrationFilesToApply) {
+      await applyDownMigration(client, schema, filename, contents, upFilename);
+    }
+    console.log("All done!");
+    console.log("New migration history:");
+    console.table(await dbMigrationHistory(client, schema));
   }
 
   client.release();

package/src/migrate.ts

@@ -3,7 +3,8 @@ import { MigrationRow } from "./types";
 
 export const validateMigrationFiles = (
   migrationFiles: { fullFilePath: string; filename: string; hash: string }[],
-  migrationHistory: MigrationRow[]
+  migrationHistory: MigrationRow[],
+  isUp: boolean = true
 ) => {
   if (migrationFiles.length === 0) {
     console.log("No migrations found");
@@ -17,7 +18,7 @@ export const validateMigrationFiles = (
     process.exit(1);
   }
 
-  if (migrationFiles.length === migrationHistory.length) {
+  if (migrationFiles.length === migrationHistory.length && isUp) {
     console.log("All migrations are already applied");
     process.exit(0);
   }
@@ -73,3 +74,55 @@ export const applyMigration = async (
     process.exit(1);
   }
 };
+
+export const validateDownMigrationFiles = (
+  downMigrationFilesToApply: { filename: string }[],
+  reverseMigrationHistory: MigrationRow[]
+) => {
+  for (let i = 0; i < downMigrationFilesToApply.length; i++) {
+    const { filename } = downMigrationFilesToApply[i];
+    if (
+      filename.split(".down.sql")[0] !==
+      reverseMigrationHistory[i].name.split(".sql")[0]
+    ) {
+      console.error(
+        `Migration ${filename} does not match the expected migration ${reverseMigrationHistory[i].name}`
+      );
+      process.exit(1);
+    }
+  }
+};
+
+export const applyDownMigration = async (
+  client: PoolClient,
+  schema: string,
+  filename: string,
+  contents: string,
+  upFilename: string
+) => {
+  try {
+    await client.query("BEGIN");
+
+    await client.query(
+      `SET search_path TO ${schema};
+    ${contents.toString()}`
+    );
+
+    await client.query(
+      `DELETE FROM ${schema}.stepwise_migrations WHERE name = $1`,
+      [upFilename]
+    );
+
+    await client.query("COMMIT");
+
+    console.log(`Applied down migration ${filename}`);
+  } catch (error) {
+    try {
+      await client.query("ROLLBACK");
+    } catch (error) {
+      console.error("Error rolling back transaction", error);
+    }
+    console.error("Error applying down migration", error);
+    process.exit(1);
+  }
+};

package/src/utils.ts

@@ -1,10 +1,10 @@
 import crypto from "crypto";
 import fs from "fs/promises";
 import path from "path";
+import { MigrationRow } from "./types";
 
-export const hashFile = async (path: string) => {
-  const file = await fs.readFile(path);
-  return crypto.createHash("sha256").update(file).digest("hex");
+export const calculateHash = (contents: string) => {
+  return crypto.createHash("sha256").update(contents).digest("hex");
 };
 
 export const usage = `
@@ -13,6 +13,8 @@ Usage: stepwise-migrations [command] [options]
 Commands:
   migrate
     Migrate the database to the latest version
+  down
+    Rollback the database to the previous version
   info
     Show information about the current state of the migrations in the database
   drop
@@ -23,6 +25,8 @@ Options:
   --schema <schema>          The schema to use for the migrations
   --path <path>              The path to the migrations directory
   --ssl true/false           Whether to use SSL for the connection (default: false)
+  --nup                      Number of up migrations to apply (default: all)
+  --ndown                    Number of down migrations to apply (default: 1)
 
 Example:
   npx stepwise-migrations \
@@ -47,7 +51,12 @@ export const validateArgs = (argv: any) => {
     console.log(usage);
     process.exit(1);
   }
-  if (argv._[0] !== "migrate" && argv._[0] !== "info" && argv._[0] !== "drop") {
+  if (
+    argv._[0] !== "migrate" &&
+    argv._[0] !== "info" &&
+    argv._[0] !== "drop" &&
+    argv._[0] !== "down"
+  ) {
     console.error(`Invalid command: ${argv._[0]}`);
     console.log(usage);
     process.exit(1);
@@ -57,22 +66,70 @@ export const validateArgs = (argv: any) => {
 export const readMigrationFiles = async (directory: string) => {
   const files = await fs.readdir(directory, { withFileTypes: true });
   const migrationFiles = files
-    .filter((file) => file.isFile() && file.name.endsWith(".sql"))
+    .filter(
+      (file) =>
+        file.isFile() &&
+        file.name.endsWith(".sql") &&
+        !file.name.endsWith(".down.sql")
+    )
     .map((file) => path.join(directory, file.name));
   migrationFiles.sort();
   const results: {
+    type: "up";
     fullFilePath: string;
     filename: string;
     hash: string;
     contents: string;
   }[] = [];
   for (const fullFilePath of migrationFiles) {
-    const hash = await hashFile(fullFilePath);
+    const contents = await fs.readFile(fullFilePath, "utf8");
+
+    results.push({
+      type: "up",
+      fullFilePath,
+      filename: path.basename(fullFilePath),
+      hash: calculateHash(contents),
+      contents,
+    });
+  }
+  return results;
+};
+
+export const fileExists = async (path: string) => {
+  try {
+    return (await fs.stat(path)).isFile();
+  } catch (error) {
+    return false;
+  }
+};
+
+export const readDownMigrationFiles = async (
+  directory: string,
+  migrationHistory: MigrationRow[]
+) => {
+  const results: {
+    type: "down";
+    fullFilePath: string;
+    filename: string;
+    upFilename: string;
+
+    contents: string;
+  }[] = [];
+  for (const migration of migrationHistory) {
+    const fullFilePath = path.join(
+      directory,
+      `${migration.name.split(".sql")[0]}.down.sql`
+    );
+    if (!(await fileExists(fullFilePath))) {
+      console.error(`Down migration file not found: ${fullFilePath}`);
+      process.exit(1);
+    }
     const contents = await fs.readFile(fullFilePath, "utf8");
     results.push({
+      type: "down",
       fullFilePath,
       filename: path.basename(fullFilePath),
-      hash,
+      upFilename: migration.name,
       contents,
     });
   }