mix pgflow.gen.pgmq_migration (PgFlow v0.1.0)

Copy Markdown View Source

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.