stepwise-migrations 1.0.16 → 1.0.17

package/README.md

@@ -41,18 +41,20 @@ Options:
   --path <path>              The path to the migrations directory
   --ssl true/false           Whether to use SSL for the connection (default: false)
   --napply                      Number of up migrations to apply (default: all)
-  --nundo                    Number of down migrations to apply (default: 1)
+  --nundo                    Number of undo migrations to apply (default: 1)
   --filename                 The filename to get the script for (default: last applied migration)
 
 Example:
   npx stepwise-migrations migrate \
     --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydatabase \
     --schema=myschema \
-    --path=./db/migration/
+    --path=./test/migrations-template/
 ```
 
 ## Examples
 
+[comment]: <> (Start of examples)
+
 ### Migrate
 
 If all files are in a valid state, runs all the "up" migrations that have not been applied yet.
@@ -61,7 +63,7 @@ If all files are in a valid state, runs all the "up" migrations that have not be
 npx stepwise-migrations migrate \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
   --schema=myschema \
-  --path=./db/migration/
+  --path=./test/migrations-template/
 ```
 
 <details>
@@ -71,36 +73,46 @@ npx stepwise-migrations migrate \
 ```text
 Creating schema myschema... done!
 Creating stepwise_migration_events table... done!
-Applying migration v1_connect_session_table.sql... done!
-Applying migration v2_auth.sql... done!
-All done! Applied 2 migrations
-Migration state:
-┌─────────┬────┬────────────────────────────────┬────────────┬──────────────────────────────┐
-│ (index) │ id │ name                           │ applied_by │ applied_at                   │
-├─────────┼────┼────────────────────────────────┼────────────┼──────────────────────────────┤
-│ 0       │ 1  │ 'v1_connect_session_table.sql' │ 'postgres' │ '2024-11-24 05:40:41.211617' │
-│ 1       │ 2  │ 'v2_auth.sql'                  │ 'postgres' │ '2024-11-24 05:40:41.214732' │
-└─────────┴────┴────────────────────────────────┴────────────┴──────────────────────────────┘
-Unapplied migrations:
+Applying versioned migration v1_first.sql... done!
+Applying versioned migration v2_second.sql... done!
+Applying versioned migration v3_third.sql... done!
+Applying repeatable migration v0_get_number.repeatable.sql... done!
+All done! Applied 4 migrations
+All applied versioned migrations:
+┌─────────┬────┬─────────────┬─────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type        │ filename        │ applied_by │ applied_at                   │
+├─────────┼────┼─────────────┼─────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 1  │ 'versioned' │ 'v1_first.sql'  │ 'postgres' │ '2024-11-25 15:25:55.799253' │
+│ 1       │ 2  │ 'versioned' │ 'v2_second.sql' │ 'postgres' │ '2024-11-25 15:25:55.80306'  │
+│ 2       │ 3  │ 'versioned' │ 'v3_third.sql'  │ 'postgres' │ '2024-11-25 15:25:55.80534'  │
+└─────────┴────┴─────────────┴─────────────────┴────────────┴──────────────────────────────┘
+All applied repeatable migrations:
+┌─────────┬────┬──────────────┬────────────────────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type         │ filename                       │ applied_by │ applied_at                   │
+├─────────┼────┼──────────────┼────────────────────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 4  │ 'repeatable' │ 'v0_get_number.repeatable.sql' │ 'postgres' │ '2024-11-25 15:25:55.807375' │
+└─────────┴────┴──────────────┴────────────────────────────────┴────────────┴──────────────────────────────┘
+Unapplied versioned migrations:
 ┌─────────┐
 │ (index) │
 ├─────────┤
+└─────────┘
 ```
 
 </details>
 
 ### Undo
 
-Runs a single down migration for the last applied migration.
-Can run multiple down migrations if the `--nundo` option is provided.
+Runs a single undo migration for the last applied migration.
+Can run multiple undo migrations if the `--nundo` option is provided.
 
 Command:
 
 ```bash
-npx stepwise-migrations down \
+npx stepwise-migrations undo \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
   --schema=myschema \
-  --path=./db/migration/
+  --path=./test/migrations-template/
 ```
 
 <details>
@@ -108,20 +120,34 @@ npx stepwise-migrations down \
 <summary>Example output</summary>
 
 ```text
-Applying down migration v2_auth.undo.sql... done!
-All done! Applied 1 down migration
-Migration state:
-┌─────────┬────┬────────────────────────────────┬────────────┬──────────────────────────────┐
-│ (index) │ id │ name                           │ applied_by │ applied_at                   │
-├─────────┼────┼────────────────────────────────┼────────────┼──────────────────────────────┤
-│ 0       │ 1  │ 'v1_connect_session_table.sql' │ 'postgres' │ '2024-11-24 05:40:41.211617' │
-└─────────┴────┴────────────────────────────────┴────────────┴──────────────────────────────┘
-Unapplied migrations:
-┌─────────┬───────────────┐
-│ (index) │ filename      │
-├─────────┼───────────────┤
-│ 0       │ 'v2_auth.sql' │
-└─────────┴───────────────┘
+[
+  {
+    type: 'undo',
+    filename: 'v3_third.undo.sql',
+    script: 'drop table third;'
+  }
+]
+Applying undo migration v3_third.undo.sql... done!
+All done! Performed 1 undo migration
+All applied versioned migrations:
+┌─────────┬────┬─────────────┬─────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type        │ filename        │ applied_by │ applied_at                   │
+├─────────┼────┼─────────────┼─────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 1  │ 'versioned' │ 'v1_first.sql'  │ 'postgres' │ '2024-11-25 15:25:55.799253' │
+│ 1       │ 2  │ 'versioned' │ 'v2_second.sql' │ 'postgres' │ '2024-11-25 15:25:55.80306'  │
+│ 2       │ 3  │ 'versioned' │ 'v3_third.sql'  │ 'postgres' │ '2024-11-25 15:25:55.80534'  │
+└─────────┴────┴─────────────┴─────────────────┴────────────┴──────────────────────────────┘
+All applied repeatable migrations:
+┌─────────┬────┬──────────────┬────────────────────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type         │ filename                       │ applied_by │ applied_at                   │
+├─────────┼────┼──────────────┼────────────────────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 4  │ 'repeatable' │ 'v0_get_number.repeatable.sql' │ 'postgres' │ '2024-11-25 15:25:55.807375' │
+└─────────┴────┴──────────────┴────────────────────────────────┴────────────┴──────────────────────────────┘
+Unapplied versioned migrations:
+┌─────────┐
+│ (index) │
+├─────────┤
+└─────────┘
 ```
 
 </details>
@@ -134,7 +160,7 @@ Validates the migration files and the stepwise_migration_events table.
 npx stepwise-migrations validate \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
   --schema=myschema \
-  --path=./db/migration/
+  --path=./test/migrations-template/
 ```
 
 <details>
@@ -143,18 +169,25 @@ npx stepwise-migrations validate \
 
 ```text
 Validation passed
-Migration state:
-┌─────────┬────┬────────────────────────────────┬────────────┬──────────────────────────────┐
-│ (index) │ id │ name                           │ applied_by │ applied_at                   │
-├─────────┼────┼────────────────────────────────┼────────────┼──────────────────────────────┤
-│ 0       │ 1  │ 'v1_connect_session_table.sql' │ 'postgres' │ '2024-11-24 05:40:41.211617' │
-└─────────┴────┴────────────────────────────────┴────────────┴──────────────────────────────┘
-Unapplied migrations:
-┌─────────┬───────────────┐
-│ (index) │ filename      │
-├─────────┼───────────────┤
-│ 0       │ 'v2_auth.sql' │
-└─────────┴───────────────┘
+All applied versioned migrations:
+┌─────────┬────┬─────────────┬─────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type        │ filename        │ applied_by │ applied_at                   │
+├─────────┼────┼─────────────┼─────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 1  │ 'versioned' │ 'v1_first.sql'  │ 'postgres' │ '2024-11-25 15:25:55.799253' │
+│ 1       │ 2  │ 'versioned' │ 'v2_second.sql' │ 'postgres' │ '2024-11-25 15:25:55.80306'  │
+└─────────┴────┴─────────────┴─────────────────┴────────────┴──────────────────────────────┘
+All applied repeatable migrations:
+┌─────────┬────┬──────────────┬────────────────────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type         │ filename                       │ applied_by │ applied_at                   │
+├─────────┼────┼──────────────┼────────────────────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 4  │ 'repeatable' │ 'v0_get_number.repeatable.sql' │ 'postgres' │ '2024-11-25 15:25:55.807375' │
+└─────────┴────┴──────────────┴────────────────────────────────┴────────────┴──────────────────────────────┘
+Unapplied versioned migrations:
+┌─────────┬─────────────┬────────────────┐
+│ (index) │ type        │ filename       │
+├─────────┼─────────────┼────────────────┤
+│ 0       │ 'versioned' │ 'v3_third.sql' │
+└─────────┴─────────────┴────────────────┘
 ```
 
 </details>
@@ -163,16 +196,17 @@ Unapplied migrations:
 
 <summary>Example output - script changed error</summary>
 
-```sql
-Error: migration v1_connect_session_table.sql has been modified, aborting.
- 	"expire" timestamp(6) NOT NULL
- )
- WITH (OIDS=FALSE);
--ALTER TABLE "session" ADD CONSTRAINT "session_pkey" PRIMARY KEY ("sid") NOT DEFERRABLE INITIALLY IMMEDIATE;
-
-+ALTER TABLE "session" ADD CONSTRAINT "session_pkey" PRIMARY KEY ("sid") NOT DEFERRABLE INITIALLY IMMEDIATE;
+```
+There were errors loading the migration state. Please fix the errors and try again.
+  - Versioned migration v1_first.sql has been altered. Cannot migrate in current state.
+
+@@ -2,3 +2,5 @@ create table first (
+   id serial primary key,
+   name text not null
+ );
 +
-+ALTER TABLE "session" ADD INDEX "session_sid" ON "session" (sid);
++ALTER TABLE first ADD COLUMN age int;
+
 ```
 
 </details>
@@ -185,7 +219,7 @@ Shows the audit history for the migrations in the database.
 npx stepwise-migrations audit \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
   --schema=myschema \
-  --path=./db/migration/
+  --path=./test/migrations-template/
 ```
 
 <details>
@@ -193,14 +227,16 @@ npx stepwise-migrations audit \
 <summary>Example output</summary>
 
 ```text
-Audit history:
-┌─────────┬────┬────────┬────────────────────────────────┬────────────┬──────────────────────────────┐
-│ (index) │ id │ type   │ name                           │ applied_by │ applied_at                   │
-├─────────┼────┼────────┼────────────────────────────────┼────────────┼──────────────────────────────┤
-│ 0       │ 1  │ 'up'   │ 'v1_connect_session_table.sql' │ 'postgres' │ '2024-11-24 05:40:41.211617' │
-│ 1       │ 2  │ 'up'   │ 'v2_auth.sql'                  │ 'postgres' │ '2024-11-24 05:40:41.214732' │
-│ 2       │ 3  │ 'down' │ 'v2_auth.undo.sql'             │ 'postgres' │ '2024-11-24 05:41:34.541462' │
-└─────────┴────┴────────┴────────────────────────────────┴────────────┴──────────────────────────────┘
+Event history:
+┌─────────┬────┬──────────────┬────────────────────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type         │ filename                       │ applied_by │ applied_at                   │
+├─────────┼────┼──────────────┼────────────────────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 1  │ 'versioned'  │ 'v1_first.sql'                 │ 'postgres' │ '2024-11-25 15:25:55.799253' │
+│ 1       │ 2  │ 'versioned'  │ 'v2_second.sql'                │ 'postgres' │ '2024-11-25 15:25:55.80306'  │
+│ 2       │ 3  │ 'versioned'  │ 'v3_third.sql'                 │ 'postgres' │ '2024-11-25 15:25:55.80534'  │
+│ 3       │ 4  │ 'repeatable' │ 'v0_get_number.repeatable.sql' │ 'postgres' │ '2024-11-25 15:25:55.807375' │
+│ 4       │ 5  │ 'undo'       │ 'v3_third.undo.sql'            │ 'postgres' │ '2024-11-25 15:25:56.588007' │
+└─────────┴────┴──────────────┴────────────────────────────────┴────────────┴──────────────────────────────┘
 ```
 
 </details>
@@ -215,7 +251,7 @@ Command:
 npx stepwise-migrations info \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
   --schema=myschema \
-  --path=./db/migration/
+  --path=./test/migrations-template/
 ```
 
 <details>
@@ -223,17 +259,30 @@ npx stepwise-migrations info \
 <summary>Example output</summary>
 
 ```text
-Migration state:
-┌─────────┬────┬────────────────────────────────┬────────────┬──────────────────────────────┐
-│ (index) │ id │ name                           │ applied_by │ applied_at                   │
-├─────────┼────┼────────────────────────────────┼────────────┼──────────────────────────────┤
-│ 0       │ 1  │ 'v1_connect_session_table.sql' │ 'postgres' │ '2024-11-24 05:40:41.211617' │
-└─────────┴────┴────────────────────────────────┴────────────┴──────────────────────────────┘
+All applied versioned migrations:
+┌─────────┬────┬─────────────┬─────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type        │ filename        │ applied_by │ applied_at                   │
+├─────────┼────┼─────────────┼─────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 1  │ 'versioned' │ 'v1_first.sql'  │ 'postgres' │ '2024-11-25 15:25:55.799253' │
+│ 1       │ 2  │ 'versioned' │ 'v2_second.sql' │ 'postgres' │ '2024-11-25 15:25:55.80306'  │
+└─────────┴────┴─────────────┴─────────────────┴────────────┴──────────────────────────────┘
+All applied repeatable migrations:
+┌─────────┬────┬──────────────┬────────────────────────────────┬────────────┬──────────────────────────────┐
+│ (index) │ id │ type         │ filename                       │ applied_by │ applied_at                   │
+├─────────┼────┼──────────────┼────────────────────────────────┼────────────┼──────────────────────────────┤
+│ 0       │ 4  │ 'repeatable' │ 'v0_get_number.repeatable.sql' │ 'postgres' │ '2024-11-25 15:25:55.807375' │
+└─────────┴────┴──────────────┴────────────────────────────────┴────────────┴──────────────────────────────┘
+Unapplied versioned migrations:
+┌─────────┬─────────────┬────────────────┐
+│ (index) │ type        │ filename       │
+├─────────┼─────────────┼────────────────┤
+│ 0       │ 'versioned' │ 'v3_third.sql' │
+└─────────┴─────────────┴────────────────┘
 ```
 
 </details>
 
-### Get Script
+### Get Applied Script
 
 Gets the script for the last applied migration.
 Can get the script for a specific migration if the `--filename` option is provided.
@@ -241,24 +290,22 @@ Can get the script for a specific migration if the `--filename` option is provid
 Command:
 
 ```bash
-npx stepwise-migrations get-script --filename v2_auth.sql \
+npx stepwise-migrations get-applied-script --filename v1_first.sql \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
   --schema=myschema \
-  --path=./db/migration/
+  --path=./test/migrations-template/
 ```
 
 <details>
 
 <summary>Example output</summary>
 
-```sql
-CREATE TABLE "users" (
-	id bigserial primary key,
-	email text unique not null,
-	first_name text not null,
-	last_name text not null,
-	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+```text
+create table first (
+  id serial primary key,
+  name text not null
 );
+
 ```
 
 </details>
@@ -272,7 +319,8 @@ Command:
 ```bash
 npx stepwise-migrations drop \
   --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
-  --schema=myschema
+  --schema=myschema \
+  --path=./test/migrations-template/
 ```
 
 <details>
@@ -280,7 +328,9 @@ npx stepwise-migrations drop \
 <summary>Example output</summary>
 
 ```text
-Dropping the tables, schema and migration stepwise_migration_events table... done!
+Dropping the tables, schema and migration history table... done!
 ```
 
 </details>
+
+[comment]: <> (End of examples)

package/dist/scripts/readme.js

@@ -0,0 +1,55 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = __importDefault(require("fs/promises"));
+const utils_1 = require("../test/utils");
+const next = (readme, from) => __awaiter(void 0, void 0, void 0, function* () {
+    const end = readme.indexOf("[comment]: <> (End of examples)");
+    if (readme.indexOf("```bash", from) < from ||
+        readme.indexOf("```bash", from) >= end) {
+        return { nextReadme: readme, nextIndex: -1 };
+    }
+    const startScript = readme.indexOf("```bash", from) + 8;
+    const endScript = readme.indexOf("```", startScript);
+    const script = readme.slice(startScript, endScript);
+    console.log(script);
+    const { output } = yield (0, utils_1.execute)(script);
+    // console.log(output);
+    const startOutput = readme.indexOf("```text", endScript) + 8;
+    const endOutput = readme.indexOf("```", startOutput);
+    return {
+        nextReadme: readme.slice(0, startOutput) + output + readme.slice(endOutput),
+        nextIndex: endOutput + 3,
+    };
+});
+(() => __awaiter(void 0, void 0, void 0, function* () {
+    let readme = yield promises_1.default.readFile("./README.md", "utf8");
+    const { output } = yield (0, utils_1.execute)(`npm exec stepwise-migrations drop -- \\
+      --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
+      --schema=myschema \\
+      --path=./test/migrations-template/ `);
+    let index = readme.indexOf("[comment]: <> (Start of examples)");
+    let i = 0;
+    while (true) {
+        const { nextReadme, nextIndex } = yield next(readme, index);
+        if (nextIndex === -1) {
+            break;
+        }
+        readme = nextReadme;
+        index = nextIndex;
+        i++;
+        // if (i > 1) break;
+    }
+    yield promises_1.default.writeFile("./README.md", readme);
+}))();

package/dist/src/state.js

@@ -103,7 +103,7 @@ const eventsToApplied = (events) => {
             }
             else if ((0, exports.getUndoFilename)(appliedVersionedMigrations[appliedVersionedMigrations.length - 1]
                 .filename) !== event.filename) {
-                errors.push("Events table is in a bad state: down migration does not match the most recently applied migration");
+                errors.push("Events table is in a bad state: undo migration does not match the most recently applied migration");
                 break;
             }
             else {

package/dist/src/utils.js

@@ -14,6 +14,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sliceFromFirstNull = exports.exitIfNotInitialized = exports.abortIfErrors = exports.fileExists = exports.printMigrationHistory = exports.printMigrationHistoryAndUnappliedMigrations = exports.readMigrationFiles = exports.filenameToType = exports.validateArgs = exports.usage = void 0;
 const promises_1 = __importDefault(require("fs/promises"));
+const git_diff_1 = __importDefault(require("git-diff"));
 const path_1 = __importDefault(require("path"));
 exports.usage = `
 Usage: stepwise-migrations [command] [options]
@@ -34,7 +35,7 @@ Options:
   --path <path>              The path to the migrations directory
   --ssl true/false           Whether to use SSL for the connection (default: false)
   --napply                      Number of up migrations to apply (default: all)
-  --nundo                    Number of down migrations to apply (default: 1)
+  --nundo                    Number of undo migrations to apply (default: 1)
 
 Example:
   npx stepwise-migrations migrate \\
@@ -87,7 +88,9 @@ const readMigrationFiles = (directory, appliedVersionedMigrations) => __awaiter(
         if (file &&
             file.type === "versioned" &&
             file.script !== appliedMigration.script) {
-            errors.push(`Versioned migration ${appliedMigration.filename} has been altered. Cannot migrate in current state.`);
+            errors.push(`Versioned migration ${appliedMigration.filename} has been altered. Cannot migrate in current state. \n\n${(0, git_diff_1.default)(appliedMigration.script, file.script, {
+                color: true,
+            })}\n\n`);
         }
     }
     return { files: results, errors };

package/dist/test/index.test.js

@@ -16,8 +16,8 @@ const node_assert_1 = __importDefault(require("node:assert"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_test_1 = require("node:test");
 const utils_1 = require("./utils");
-const connection = "postgresql://postgres:postgres@127.0.0.1:5432/stepwise-db";
-const schema = "stepwise";
+const connection = "postgresql://postgres:postgres@127.0.0.1:5432/mydb";
+const schema = "testschema";
 const paths = {
     valid: "./test/migrations-valid",
     invalid: "./test/migrations-invalid",

package/docker-compose.yml

@@ -1,9 +1,9 @@
 services:
-  stepwise-db:
-    container_name: stepwise-db
+  mydb:
+    container_name: mydb
     image: postgres:17.2
     environment:
-      POSTGRES_DB: stepwise-db
+      POSTGRES_DB: mydb
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
     healthcheck:

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "stepwise-migrations",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "",
-  "main": "dist/src/index.js",
+  "main": "./dist/src/index.js",
   "scripts": {
     "build": "tsc",
     "test": "npm run build; glob -c \"tsx --test --test-reporter spec \" \"./test/**/*.test.ts\"",
@@ -24,7 +24,7 @@
     "tsx": "^4.19.2"
   },
   "bin": {
-    "stepwise-migrations": "dist/src/index.js"
+    "stepwise-migrations": "./dist/src/index.js"
   },
   "dependencies": {
     "git-diff": "^2.0.6",

package/scripts/readme.ts

@@ -0,0 +1,50 @@
+import fs from "fs/promises";
+import { execute } from "../test/utils";
+
+const next = async (readme: string, from: number) => {
+  const end = readme.indexOf("[comment]: <> (End of examples)");
+
+  if (
+    readme.indexOf("```bash", from) < from ||
+    readme.indexOf("```bash", from) >= end
+  ) {
+    return { nextReadme: readme, nextIndex: -1 };
+  }
+
+  const startScript = readme.indexOf("```bash", from) + 8;
+  const endScript = readme.indexOf("```", startScript);
+  const script = readme.slice(startScript, endScript);
+  console.log(script);
+  const { output } = await execute(script);
+  // console.log(output);
+  const startOutput = readme.indexOf("```text", endScript) + 8;
+  const endOutput = readme.indexOf("```", startOutput);
+  return {
+    nextReadme: readme.slice(0, startOutput) + output + readme.slice(endOutput),
+    nextIndex: endOutput + 3,
+  };
+};
+
+(async () => {
+  let readme = await fs.readFile("./README.md", "utf8");
+  const { output } = await execute(`npm exec stepwise-migrations drop -- \\
+      --connection=postgresql://postgres:postgres@127.0.0.1:5432/mydb \
+      --schema=myschema \\
+      --path=./test/migrations-template/ `);
+
+  let index = readme.indexOf("[comment]: <> (Start of examples)");
+  let i = 0;
+  while (true) {
+    const { nextReadme, nextIndex } = await next(readme, index);
+    if (nextIndex === -1) {
+      break;
+    }
+
+    readme = nextReadme;
+    index = nextIndex;
+    i++;
+    // if (i > 1) break;
+  }
+
+  await fs.writeFile("./README.md", readme);
+})();

package/src/state.ts

@@ -146,7 +146,7 @@ export const eventsToApplied = (
         ) !== event.filename
       ) {
         errors.push(
-          "Events table is in a bad state: down migration does not match the most recently applied migration"
+          "Events table is in a bad state: undo migration does not match the most recently applied migration"
         );
         break;
       } else {

package/src/utils.ts

@@ -1,4 +1,5 @@
 import fs from "fs/promises";
+import gitDiff from "git-diff";
 import path from "path";
 import {
   AppliedMigration,
@@ -26,7 +27,7 @@ Options:
   --path <path>              The path to the migrations directory
   --ssl true/false           Whether to use SSL for the connection (default: false)
   --napply                      Number of up migrations to apply (default: all)
-  --nundo                    Number of down migrations to apply (default: 1)
+  --nundo                    Number of undo migrations to apply (default: 1)
 
 Example:
   npx stepwise-migrations migrate \\
@@ -89,7 +90,15 @@ export const readMigrationFiles = async (
       file.script !== appliedMigration.script
     ) {
       errors.push(
-        `Versioned migration ${appliedMigration.filename} has been altered. Cannot migrate in current state.`
+        `Versioned migration ${
+          appliedMigration.filename
+        } has been altered. Cannot migrate in current state. \n\n${gitDiff(
+          appliedMigration.script,
+          file.script,
+          {
+            color: true,
+          }
+        )}\n\n`
       );
     }
   }

package/test/index.test.ts

@@ -2,8 +2,8 @@ import assert from "node:assert";
 import fs from "node:fs";
 import { beforeEach, describe, it } from "node:test";
 import { assertIncludesAll, assertIncludesExcludesAll, execute } from "./utils";
-const connection = "postgresql://postgres:postgres@127.0.0.1:5432/stepwise-db";
-const schema = "stepwise";
+const connection = "postgresql://postgres:postgres@127.0.0.1:5432/mydb";
+const schema = "testschema";
 
 const paths = {
   valid: "./test/migrations-valid",

package/test/migrations-template/v1_first.sql

@@ -2,3 +2,5 @@ create table first (
   id serial primary key,
   name text not null
 );
+
+ALTER TABLE first ADD COLUMN age int;