Registry / database / pgqueuer

pgqueuer

JSON →
library1.0.2pypypi✓ verified 84d ago

Pgqueuer is a Python library that utilizes PostgreSQL as a robust and efficient backend for asynchronous job queuing and scheduling. It supports both one-off jobs and recurring tasks via cron-like schedules, offering an in-memory driver for development and testing. The library is actively developed, with frequent releases bringing architectural improvements, new features, and bug fixes. The current version is 0.26.3.

pip install pgqueuer
INSTALL
IMPORT
SIG · PGQUEUER
P
pgqueuer
databasepythonv1.0.2
Install
5.1s avg
Import
902ms
Disk
58MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✓ —
✓ 6.1s
py 3.11
✓ —
✓ 5.1s
py 3.12
✓ —
✓ 4.65s
py 3.13
✓ —
✓ 4.65s
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.")
Debug
Known issues
breakingStarting from v0.26.3, `PgQueuer.run()` no longer silently swallows crashes from its internal `QueueManager` or `SchedulerManager`. Instead, exceptions from these managers will now propagate immediately to the caller, preventing silent hangs or exits.
fix
Update your error handling logic around `PgQueuer.run()` to catch and manage potential exceptions. This change improves observability of critical failures.
affects: >=0.26.3
gotchaAll task functions registered with `pg.worker.register_task()` must be `async def` functions. Passing a synchronous function will lead to runtime errors when the worker attempts to execute it.
fix
Ensure your task functions are defined using `async def` and `await` any asynchronous operations within them.
affects: All versions
gotchaIncorrect PostgreSQL connection details (host, port, user, password, database name) will prevent `PgQueuer` from connecting, leading to `asyncpg.exceptions.CannotConnectNowError` or `InvalidCatalogNameError`.
fix
Verify your `DATABASE_URL` string or the parameters passed to `PgQueuer.from_asyncpg_url` match your PostgreSQL server's configuration and ensure the database exists.
affects: All versions
gotchaPrior to v0.25.1, `PgQueuer` could, in certain crash scenarios, leave jobs in a 'picked' state, making them stuck and not retried. This was addressed by improved retry dequeue logic.
fix
Upgrade to `pgqueuer` v0.25.1 or newer to benefit from the improved job reclamation logic that automatically retries stale 'picked' jobs after worker crashes.
affects: <0.25.1
gotchaScheduler race conditions related to how `PgQueuer` handles concurrent scheduling of tasks were fixed in v0.26.1.
fix
Upgrade to `pgqueuer` v0.26.1 or newer to ensure more robust and reliable scheduling, especially under heavy load or in distributed environments.
affects: <0.26.1
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.
fix
Create 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.
fix
Ensure 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.
fix
Change 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()`.
fix
Before 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).
fix
Ensure 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.
Agent activity
26 hits · last 30 days
node
24
OpenAI (training)
1
Resources
pgqueuer — pip install pgqueuer · libregistry