Skip to content

Getting Started

Prerequisites

  • Python 3.10 or newer.
  • A running PostgreSQL instance with the PGMQ extension installed.

Installation

Install the base package from PyPI:

pip install pgmq

Optional Extras

Extra Command Backend
Async pip install pgmq[async] asyncpg
SQLAlchemy (sync) pip install pgmq[sqlalchemy] SQLAlchemy + psycopg
SQLAlchemy (async) pip install pgmq[sqlalchemy-async] SQLAlchemy + asyncpg
HTTP API pip install pgmq[fastapi] FastAPI + uvicorn (see HTTP API)

You can also install everything at once:

pip install pgmq[async,sqlalchemy,sqlalchemy-async,fastapi]

Start a Local Postgres with PGMQ

The fastest way to get started is with the pre-built Docker image, where PGMQ comes pre-installed as an extension in Postgres:

docker run -d --name pgmq-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  ghcr.io/pgmq/pg18-pgmq:latest

Then connect and enable PGMQ:

psql postgres://postgres:postgres@localhost:5432/postgres -c "CREATE EXTENSION pgmq;"

SQL Only

You can also use psql to install PGMQ's objects directly into the pgmq schema in Postgres. Use this method in environments that do not natively support the PGMQ extension or where extension management is handled manually.

git clone https://github.com/pgmq/pgmq.git
cd pgmq
psql -f pgmq-extension/sql/pgmq.sql postgres://postgres:postgres@localhost:5432/postgres

Or install directly from Python using the SQL script bundled with pgmq:

from pgmq import install_pgmq_from_sql

install_pgmq_from_sql(
    host="localhost",
    port="5432",
    username="postgres",
    password="postgres",
    database="postgres",
)

See SQL Installation for connection options, exceptions, and Makefile helpers.

SQL-only install does not support extension versioning or upgrades (CREATE EXTENSION / ALTER EXTENSION ... UPDATE). Those only work when PGMQ is installed as a formal Postgres extension. The Python helper applies a pinned snapshot of pgmq.sql and is not an upgrade tool.

In these environments, automatic extension initialization can be disabled by setting init_extension=False when creating the client instance.

Example:

from pgmq import PGMQueue

client = PGMQueue(
    host=host,
    port=port,
    username=username,
    password=password,
    database=database,
    init_extension=False
)

When init_extension=False is set, the client will not attempt to run:

CREATE EXTENSION IF NOT EXISTS pgmq CASCADE;

This option is supported by both sync and async clients.

Your First Queue

Create a file named quickstart.py:

from pgmq import PGMQueue

# Connect using environment variables or defaults
queue = PGMQueue()

# Create a queue
queue.create_queue("my_queue")

# Send a message
msg_id = queue.send("my_queue", {"task": "send_email", "to": "user@example.com"})
print(f"Sent message {msg_id}")

# Read a message (invisible for 30 seconds)
msg = queue.read("my_queue", vt=30)
print(f"Received: {msg.message}")

# Archive it when done
queue.archive("my_queue", msg.msg_id)

Run it:

python quickstart.py

Environment Variables

If you prefer not to hard-code credentials, set these variables before running your script:

export PG_HOST=127.0.0.1
export PG_PORT=5432
export PG_USERNAME=postgres
export PG_PASSWORD=postgres
export PG_DATABASE=postgres
# Or use a full connection string:
export DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

Next Steps