# `mix pgflow.gen.pgmq_migration`
[🔗](https://github.com/agoodway/pgflow/blob/v0.1.0/lib/mix/tasks/pgflow.gen.pgmq_migration.ex#L1)

Downloads the pgmq SQL-only install bundle from the official pgmq/pgmq
repository at task-runtime, persists it into the consuming app's `priv/`
tree, and generates an Ecto migration that applies it.

pgflow requires pgmq 1.8+ for `LISTEN/NOTIFY` dispatch. This task is the
recommended way to install pgmq for apps using pgflow on hosts where pgmq
is not available as a native extension (Neon, Supabase, self-hosted
without build tools).

## Usage

    mix pgflow.gen.pgmq_migration
    mix pgflow.gen.pgmq_migration --version 1.11.0
    mix pgflow.gen.pgmq_migration --url https://... --sha256 <hash>
    mix pgflow.gen.pgmq_migration --migrations-path priv/repo/migrations

## Options

  * `--version` - pgmq version tag to fetch. Default: `1.11.0`.
    Must be a key in the internal known-versions map, OR paired with
    `--url` and `--sha256` for custom versions.

  * `--url` - Override the upstream URL. Requires `--sha256`.

  * `--sha256` - Expected sha256 of the downloaded bytes. Required when
    `--url` is used; otherwise looked up from the known-versions map.

  * `--migrations-path` - Where to write the generated migration.
    Default: `priv/repo/migrations`.

  * `--skip-sha256` - Skip integrity check. Emits a loud warning. Not
    recommended outside of local experimentation.

## Files written

  * `priv/pgflow/pgmq/pgmq-<version>.sql` — the bundled SQL, committed to
    your repo so `mix ecto.migrate` never needs network access.

  * `priv/repo/migrations/<timestamp>_install_pgmq.exs` — the Ecto
    migration wrapper.

## Generated migration shape

    defmodule MyApp.Repo.Migrations.InstallPgmq do
      use Ecto.Migration

      @disable_ddl_transaction true
      @disable_migration_lock true

      @sql_relpath "pgflow/pgmq/pgmq-1.11.0.sql"

      def up do
        path = Path.join(:code.priv_dir(:my_app), @sql_relpath)
        execute(File.read!(path))
      end

      def down do
        execute("DROP SCHEMA IF EXISTS pgmq CASCADE")
      end
    end

## Known versions

%{
  "1.11.0" => "89f9d8a3adc43434afcf814c4afc3ef8957a20418eb120801922435238714e7a"
}

## Why fetch at task-runtime

Bundling the ~2000-line pgmq SQL in pgflow's `priv/` would bloat the dep
and couple pgflow releases to pgmq releases. Fetching once at generation
time and persisting to the consuming repo keeps pgflow slim and makes
the SQL reviewable in the consumer's git history. `mix ecto.migrate`
never needs network; it reads the persisted file.

---

*Consult [api-reference.md](api-reference.md) for complete listing*