feat: naming-flat, emit-bundle (fast deploy), and import-granularity examples

Author: pyramation

README.md

@@ -42,9 +42,11 @@ produced it.
 | [diff-migration](examples/diff-migration) | [the module (v1)](examples/import-dump/output/shop) vs [shop.v2.sql](examples/diff-migration/input/shop.v2.sql) | [migration module](examples/diff-migration/output/shop-v1-to-v2) + [delta as one SQL file](examples/diff-migration/output/shop.v1-to-v2.sql) |
 | [fold-atomic-statements](examples/fold-atomic-statements) | [atomic statement soup](examples/fold-atomic-statements/input/blog.atomic.sql) (empty `CREATE TABLE ()` + one `ADD COLUMN` per statement) | [grouped module](examples/fold-atomic-statements/output/blog) with fully folded CREATE TABLEs |
 | [flatten-history](examples/flatten-history) | [evolution log with churn](examples/flatten-history/input/inventory.churn.sql) (ADD then DROP column, late NOT NULL) | [flattened module](examples/flatten-history/output/inventory) |
+| [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` |
 
-More examples are planned (`--naming flat`, bundles + `deploy --fast`,
-`--append-module`, live-db diff sides) — see the full combination matrix in
+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).
 
 ## Layout

examples/emit-bundle/README.md

@@ -0,0 +1,12 @@
+# emit-bundle — module → content-addressed bundle (+ fast deploy)
+
+**Input:** [`../import-dump/output/shop/`](../import-dump/output/shop)
+
+**Output:** [`output/shop.bundle.tar.gz`](output/shop.bundle.tar.gz) — the whole module projected into a single content-addressed archive (`pgpm-bundle.json`: manifest, deploy order, and every change's scripts).
+
+```sh
+pgpm transform --granularity object --cwd examples/import-dump/output/shop \
+  --out /tmp/roundtrip --emit-bundle "$PWD/examples/emit-bundle/output/shop.bundle.tar.gz"
+```
+
+Bundles power `pgpm deploy --fast`: one-shot SQL plus a bulk migration ledger, reading a module's verified `sql/*.bundle.tar.gz` artifact when present and building it from `deploy/` when not. CI deploys the shop module with `--fast` and asserts the catalog is identical to the normal change-by-change deploy.

examples/emit-bundle/output/shop.bundle.tar.gz

@@ -0,0 +1,12 @@
+# import-granularity — dial granularity at import time
+
+**Input:** [`../import-dump/input/shop.v1.sql`](../import-dump/input/shop.v1.sql) — the same raw dump as [import-dump](../import-dump).
+
+**Output:** [`output/shop-atomic-direct/`](output/shop-atomic-direct) — imported straight to **atomic** granularity in one step (no intermediate object-granularity module): each table change is an empty `CREATE TABLE` plus one `ALTER TABLE` per column/constraint.
+
+```sh
+pgpm import examples/import-dump/input/shop.v1.sql --pkg shop-atomic-direct \
+  --granularity atomic --out examples/import-granularity/output
+```
+
+Demonstrates that the dials compose with any entry point: `import --granularity atomic` ≡ `import` then `transform --granularity atomic`. CI proves the catalog is identical to every other variant.

examples/import-granularity/README.md

@@ -0,0 +1,14 @@
+-- Deploy: schemas/audit/procedures/log_order_change/procedure
+-- made with <3 @ constructive.io
+
+-- requires: schemas/audit/schema
+
+
+CREATE FUNCTION audit.log_order_change() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  INSERT INTO audit.change_log (table_name, row_id, operation)
+  VALUES (TG_TABLE_NAME, NEW.id, TG_OP);
+  RETURN NEW;
+END;
+$$;
+

examples/import-granularity/output/shop-atomic-direct/deploy/schemas/audit/procedures/log_order_change/procedure.sql

@@ -0,0 +1,10 @@
+-- Deploy: schemas/audit/schema
+-- made with <3 @ constructive.io
+
+
+
+
+CREATE SCHEMA audit;
+
+COMMENT ON SCHEMA audit IS 'Append-only change log for shop tables.';
+

examples/import-granularity/output/shop-atomic-direct/deploy/schemas/audit/schema.sql

@@ -0,0 +1,35 @@
+-- Deploy: schemas/audit/tables/change_log/table
+-- made with <3 @ constructive.io
+
+-- requires: schemas/audit/schema
+
+
+CREATE TABLE audit.change_log (
+
+);
+
+ALTER TABLE audit.change_log 
+  ADD COLUMN id bigint
+    GENERATED ALWAYS AS IDENTITY
+    NOT NULL;
+
+ALTER TABLE audit.change_log 
+  ADD COLUMN table_name text
+    NOT NULL;
+
+ALTER TABLE audit.change_log 
+  ADD COLUMN row_id uuid
+    NOT NULL;
+
+ALTER TABLE audit.change_log 
+  ADD COLUMN operation text
+    NOT NULL;
+
+ALTER TABLE audit.change_log 
+  ADD COLUMN changed_at timestamptz
+    DEFAULT now()
+    NOT NULL;
+
+ALTER TABLE ONLY audit.change_log 
+  ADD CONSTRAINT change_log_pkey PRIMARY KEY (id);
+

examples/import-granularity/output/shop-atomic-direct/deploy/schemas/audit/tables/change_log/table.sql

@@ -0,0 +1,16 @@
+-- Deploy: schemas/shop/procedures/order_total/procedure
+-- made with <3 @ constructive.io
+
+-- requires: schemas/shop/schema
+
+
+CREATE FUNCTION shop.order_total(
+  p_order_id uuid
+) RETURNS int LANGUAGE sql STABLE AS $$
+  SELECT COALESCE(SUM(quantity * unit_price_cents), 0)::integer
+  FROM shop.order_items
+  WHERE order_id = p_order_id;
+$$;
+
+COMMENT ON FUNCTION shop.order_total(p_order_id uuid) IS 'Sum of line totals for an order, in cents.';
+

examples/import-granularity/output/shop-atomic-direct/deploy/schemas/shop/procedures/order_total/procedure.sql

@@ -0,0 +1,12 @@
+-- Deploy: schemas/shop/schema
+-- made with <3 @ constructive.io
+
+
+
+
+CREATE SCHEMA shop;
+
+COMMENT ON SCHEMA shop IS 'Storefront: customers, products, orders.';
+
+GRANT USAGE ON SCHEMA shop TO app_user;
+

examples/import-granularity/output/shop-atomic-direct/deploy/schemas/shop/schema.sql

@@ -0,0 +1,8 @@
+-- Deploy: schemas/shop/sequences/order_number_seq
+-- made with <3 @ constructive.io
+
+-- requires: schemas/shop/schema
+
+
+CREATE SEQUENCE shop.order_number_seq START 1000 INCREMENT 1 NO MINVALUE NO MAXVALUE CACHE 1;
+