# pgmq-migration
`pgmq-migration` exposes the PGMQ schema as a native `pg-migrate` component. Applications
compose `pgmqMigrations` into their migration plan; the package intentionally ships no
standalone runner.
Fresh databases run all six native migrations and reach PGMQ 1.13.0. Databases installed by
`pgmq-migration` 0.3 or earlier must import their `public.schema_migrations` predecessor
history before the first native `up`, so the PGMQ baseline is recorded rather than replayed.
The immutable 1.11 baseline and local notification hardening are followed by the pristine
1.12 upgrade, pristine 1.13 upgrade, and a separate four-argument partition re-entry override.
Existing native ledgers run only their pending suffix. Complete that suffix before allowing
application queue-creation traffic; each SQL migration is transactional separately.
The 1.12 checkpoint exists for compatibility testing, not as a public installation mode.
Partitioned queues still require pg_partman. The 1.13 upgrade preserves existing messages
and changes active partitioned queue IDs to `GENERATED BY DEFAULT`, enabling pg_partman
to move spilled rows with their original IDs. It does not recover spills or schedule maintenance.
`default_partition_length` estimates rows in both queue and archive default partitions;
refresh their statistics with ANALYZE when diagnosing or verifying recovery.
Run the required partition acceptance with:
```bash
nix develop .#partman --command cabal test pgmq-migration:pgmq-migration-test --test-show-details=direct
```
That shell sets `PGMQ_REQUIRE_PARTMAN=1`; missing or unusable pg_partman fails the tests.
The direct/effect/config fixtures accept `PGMQ_TEST_SCHEMA_VERSION=1.12.0|1.13.0` and
default to the complete native ledger. They package the tagged 1.12 SQL fixture.
The existing `pgmqHasqlMigrationSourceConfig` helper requires an exclusive predecessor
ledger. When an application deliberately shares that table with its own migrations, use the
explicit policy-aware constructor:
```haskell
pgmqHasqlMigrationSourceConfigWithPolicy
provider
DirectFullInstallHistory
AllowUnselectedSourceRows
```
Call `readHasqlMigrationHistory` with that configuration first and review `unselectedRows`.
The policy accepts but never claims or modifies those rows. It does not relax selected PGMQ
evidence: the baseline must still reproduce its exact stored base64 MD5, and the equivalent
two-step history still requires its state validator plus explicit equivalent-history opt-in.
The repository guide at `docs/user/schema-migration.md` contains complete fresh-install,
history-import, validation, and recovery examples.