Install & Compatibility
Where this runs
tested against v1.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PgQueuer
✓ from pgqueuer import PgQueuer
JobResult
✓ from pgqueuer.models import JobResult
InMemoryDriver
✓ from pgqueuer import InMemoryDriver
Use this for local development/testing without a real PostgreSQL database.
This quickstart demonstrates how to set up `PgQueuer` with a PostgreSQL database, register an asynchronous task, enqueue a job, and run the queue to process it. It uses `os.environ.get` for the database URL, defaulting to a common local PostgreSQL setup. Ensure a PostgreSQL server is running and accessible at the specified `DATABASE_URL`.
import asyncio
import os
from pgqueuer import PgQueuer
from pgqueuer.models import JobResult
# DATABASE_URL should point to your PostgreSQL instance.
# Example: "postgresql://user:password@localhost:5432/mydb"
# For local testing, ensure a PostgreSQL instance is running.
DATABASE_URL = os.environ.get(
"DATABASE_URL",
"postgresql://postgres:postgres@localhost:5432/pgqueuer_test_db" # Default for local testing
)
async def my_task(job_id: str, payload: dict) -> str:
"""An asynchronous task that processes data."""
print(f"[TASK] Processing job {job_id} with payload: {payload}")
await asyncio.sleep(0.5) # Simulate async I/O or computation
result = f"Task {job_id} processed: {payload['message']}"
print(f"[TASK] {result}")
return result
async def main():
print(f"[MAIN] Connecting to PostgreSQL at: {DATABASE_URL}")
# Initialize PgQueuer using your PostgreSQL database URL
# This requires a running PostgreSQL database accessible at DATABASE_URL.
pg = await PgQueuer.from_asyncpg_url(DATABASE_URL)
# Ensure necessary database tables are set up
print("[MAIN] Running database migrations...")
await pg.run_migrations()
# Register your task function with the worker
pg.worker.register_task(my_task)
print("[MAIN] Task 'my_task' registered.")
# Enqueue a job with a specific task name and payload
payload = {"message": "Hello from PgQueuer!"}
job_id = await pg.enqueue("my_task", payload)
print(f"[MAIN] Enqueued job with ID: {job_id} for task 'my_task'.")
# Run the PgQueuer event loop to process jobs.
# For a quickstart, we run it once and process existing jobs for a short duration.
# In a production setup, this would typically run indefinitely.
print("[MAIN] Running PgQueuer to process enqueued jobs (running once for 10 seconds)...")
await pg.run(once=True, timeout=10) # Process all currently enqueued jobs and then exit
# Fetch and display the result of the enqueued job
print(f"[MAIN] Fetching result for job {job_id}...")
job_result: JobResult = await pg.fetch_job_result(job_id)
if job_result:
print(f"[MAIN] Job {job_id} status: {job_result.status}")
if job_result.status == "completed":
print(f"[MAIN] Job {job_id} result: {job_result.result}")
elif job_result.status == "failed":
print(f"[MAIN] Job {job_id} failed with error: {job_result.error_message}")
else:
print(f"[MAIN] Job {job_id} result not found or not yet processed.")
# Clean up resources (close database connections)
await pg.close()
print("[MAIN] PgQueuer resources closed.")
if __name__ == "__main__":
try:
asyncio.run(main())
except Exception as e:
print(f"\n[ERROR] An error occurred: {e}")
print("Please ensure your PostgreSQL database is running and accessible at the DATABASE_URL provided.")
Errors
Common errors & fixes
asyncpg.exceptions.InvalidCatalogNameError: database "non_existent_db" does not exist
The database name specified in the `DATABASE_URL` does not exist on the PostgreSQL server.
fixCreate the specified database on your PostgreSQL server or correct the database name in your `DATABASE_URL`.
asyncpg.exceptions.CannotConnectNowError: could not connect to server: Connection refused
Pgqueuer could not establish a connection to the PostgreSQL server. This typically means the server is not running, is inaccessible from where Pgqueuer is running, or the host/port in the `DATABASE_URL` is incorrect.
fixEnsure your PostgreSQL server is running, listening on the correct host/port, and is accessible (e.g., firewall rules). Double-check the host and port in your `DATABASE_URL`.
TypeError: 'function' object is not awaitable
You registered a synchronous Python function with `pg.worker.register_task()` but Pgqueuer expects an `async def` function that can be awaited.
fixChange your task function definition from `def my_task(...)` to `async def my_task(...)` and ensure any internal asynchronous calls use `await`.
KeyError: 'my_unknown_task'
You attempted to enqueue a job with a task name (e.g., 'my_unknown_task') that has not been registered with `pg.worker.register_task()`.
fixBefore enqueuing a job, ensure that the task function corresponding to its name has been registered using `pg.worker.register_task(your_async_function)`.
TypeError: Object of type <YourObject> is not JSON serializable
The payload passed to `pg.enqueue()` contains an object that cannot be serialized to JSON (e.g., a custom class instance, a set, or other non-JSON compatible types).
fixEnsure that the `payload` argument for `pg.enqueue()` is a dictionary containing only JSON-serializable types (strings, numbers, booleans, lists, and other dictionaries).
Upgrade
Version history
1.0.2latest on PyPI · released May 29, 2026
Audit
Dependencies
asyncpgrequiredDefault asynchronous PostgreSQL driver for production use.