feat: append-migration (living migration module) and diff-live-db examples

Author: pyramation

.github/workflows/ci.yml

@@ -82,6 +82,7 @@ jobs:
           sudo apt-get update -qq
           sudo apt-get install -y -qq postgresql-client-18
           echo "PG_DUMP=/usr/lib/postgresql/18/bin/pg_dump" >> "$GITHUB_ENV"
+          echo "/usr/lib/postgresql/18/bin" >> "$GITHUB_PATH"
 
       - name: Seed pg and app_user
         run: |

.gitignore

@@ -2,4 +2,6 @@
 **/.DS_Store
 **/dist
 **/pnpm-debug.log
-lerna-debug.log
+lerna-debug.log
+# generated at test time by scripts/acceptance.sh (diff-live-db example)
+examples/diff-live-db/output/

README.md

@@ -45,9 +45,13 @@ produced it.
 | [import-granularity](examples/import-granularity) | [raw pg_dump](examples/import-dump/input/shop.v1.sql) | [atomic module in one step](examples/import-granularity/output/shop-atomic-direct) (`import --granularity atomic`) |
 | [naming-flat](examples/naming-flat) | [the module](examples/import-dump/output/shop) | [flat change-path layout](examples/naming-flat/output/shop-object) (`--naming flat`) |
 | [emit-bundle](examples/emit-bundle) | [the module](examples/import-dump/output/shop) | [content-addressed bundle](examples/emit-bundle/output/shop.bundle.tar.gz) powering `pgpm deploy --fast` |
+| [append-migration](examples/append-migration) | v1→v2 delta + [shop.v3.sql](examples/append-migration/input/shop.v3.sql) | [one living migration module](examples/append-migration/output/shop-migrations) (`diff --append-module`) covering v1→v3 |
+| [diff-live-db](examples/diff-live-db) | two **live databases** (`db:a` vs `db:b`) | migration module generated on demand at test time |
 
-More examples are planned (`--append-module`, live-db diff sides) — see the full combination matrix in
-[constructive-planning#1344](https://github.com/constructive-io/constructive-planning/issues/1344).
+See the full combination matrix in
+[constructive-planning#1344](https://github.com/constructive-io/constructive-planning/issues/1344);
+the remaining unbuilt rows are blocked on known `pgpm diff` raw-SQL
+normalization bugs or on CLI features that haven't landed yet.
 
 ## Layout
 

examples/append-migration/README.md

@@ -0,0 +1,21 @@
+# append-migration — a living migration module (v1 → v2 → v3)
+
+**Input:** [`../import-dump/output/shop/`](../import-dump/output/shop) (v1), [`../diff-migration/input/shop.v2.sql`](../diff-migration/input/shop.v2.sql) (v2), and [`input/shop.v3.sql`](input/shop.v3.sql) (v3 = v2 + a `shop.coupons` table).
+
+**Output:** [`output/shop-migrations/`](output/shop-migrations) — ONE migration module that accumulates deltas over time: the v1→v2 delta emitted first, then the v2→v3 delta **appended** into the same module (existing changes, scripts, and `.control` untouched).
+
+```sh
+# v1 -> v2: emit the initial migration module
+pgpm import examples/diff-migration/input/shop.v2.sql --pkg shop-v2 --out /tmp/v2mod
+pgpm diff examples/import-dump/output/shop /tmp/v2mod/shop-v2 \
+  --emit-migration examples/append-migration/output --pkg shop-migrations
+
+# v2 -> v3: append the next delta into the SAME module
+pgpm import examples/append-migration/input/shop.v3.sql --pkg shop-v3 --out /tmp/v3mod
+pgpm diff /tmp/v2mod/shop-v2 /tmp/v3mod/shop-v3 \
+  --append-module examples/append-migration/output/shop-migrations
+```
+
+CI deploys shop@v1 then `shop-migrations` and asserts the catalog equals v3 loaded fresh — one deploy covers the whole v1→v3 history.
+
+Note: appended changes whose derived path collides with an existing change in the module (e.g. two deltas both altering `shop.orders`) are currently skipped with a notice rather than sequenced — tracked upstream in [constructive-planning#1344](https://github.com/constructive-io/constructive-planning/issues/1344).