# @pgpmjs/bundle
The pgpm **migration bundle** — the portable, content-addressed artifact layer on top
of `@pgpmjs/ast`. A `MigrationBundle` is a deterministic snapshot of a pgpm module (plan,
control, ordered changes, per-change/whole-bundle sha256 digests) plus optional
provenance: the "shipping container" for a database migration.
- `createBundle` / `bundleFromModule` — build a bundle from a module AST.
- `writeBundleFile` / `readBundleFile` — JSON serialization on the wire.
- `materializeBundle` — expand a bundle back into a deployable module directory.
- `verifyBundle` — recompute digests and localize any tamper/mismatch.
- `transpileBundle` — produce a namespaced bundle (caller supplies the SQL AST rewrite).
- `diffBundles` / `reconcilePlan` — structural diff and ordered revert/deploy plan.
## The bundle envelope
The **bundle envelope** is how you ship a database the way you ship a product: the
whole thing — its structure (a `MigrationBundle`), its row data, its fixtures — as one
sealed, versioned, tamper-evident package. Like a shipping container: standardized,
stackable, verifiable at every port. The bundle is the schema; the envelope is the
whole shipment.
```ts
import { bundleFromModule, createEnvelope, verifyEnvelope, materializeEnvelope } from '@pgpmjs/bundle';
const envelope = createEnvelope({
version: '1.0.0', // caller-assigned artifact version
schema: bundleFromModule(moduleDir), // required: the MigrationBundle
data: [{ name: 'source-plane-data', deploy, revert, verify }], // e.g. from @pgpmjs/export
fixtures: [{ name: 'seed-roles', deploy }],
provenance: { sourceDatabase, sliceSpec } // lineage; recorded but excluded from the digest
});
verifyEnvelope(envelope); // { issues: [], schemaIssues: [] }
materializeEnvelope(envelope, outDir); // deterministic, tar-friendly directory layout
```
- **Manifest** — identity (`name`, `version`), a contents inventory with per-part
sha256 digests, and source lineage (`provenance`).
- **Merkle content digest** — the envelope digest covers the ordered part digests; the
schema part's digest is the bundle's own manifest digest, so the chain extends down
through every change and script. Flip one byte anywhere and `verifyEnvelope`
localizes it.
- **Payload-agnostic parts** — each data/fixtures part is a named deploy/revert/verify
SQL triplet produced by the caller (e.g. the `@pgpmjs/export` data-dump builders);
the envelope never generates SQL, it digests, ships, and verifies it.
- **Serialization** — one JSON artifact (`writeEnvelopeFile` / `readEnvelopeFile`) or a
deterministic directory (`materializeEnvelope` / `envelopeFromDirectory`):
```
envelope.json # manifest only
schema/pgpm-bundle.json # the schema MigrationBundle artifact
data//{deploy,revert,verify}.sql
fixtures//{deploy,revert,verify}.sql
```
This package is pure (no database, no deploy engine). The deployment glue —
`applyBundle` and `applyEnvelope`, which drive `PgpmMigrate` — lives in
`@pgpmjs/core`. See the `pgpm-migration-bundle` skill for the full model.
---
## Education and Tutorials
1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
Get started with modular databases in minutes. Install prerequisites and deploy your first module.
2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
Master the workflow for adding, organizing, and managing database changes with pgpm.
4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
Common issues and solutions for pgpm, PostgreSQL, and testing.
## Related Constructive Tooling
### 📦 Package Management
* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
### 🧪 Testing
* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
### 🧠 Parsing & AST
* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
### 📚 Documentation & Skills
* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
Install skills for AI coding agents:
```bash
# All platform skills (security, blueprints, codegen, billing, etc.)
npx skills add constructive-io/constructive-skills
# Individual repo skills (pgpm, testing, CLI, search, etc.)
npx skills add https://github.com/constructive-io/constructive --skill pgpm
npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
```
## Credits
**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
## Disclaimer
AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.