Skip to main content

pgtask

Durable tasks and workflows that live entirely in PostgreSQL.

There is no broker, no coordinator, and no extension to install. If your database is up, your queue is up.

Installation

pip install pgtask

Define a task and run a worker

A registry maps a task name to the function that runs it. A worker claims work for that queue, one lease at a time, so a worker that dies hands its tasks back instead of taking them with it.

from __future__ import annotations

import asyncio
import os

from pgtask import Client, Task, TaskRegistry, Worker

tasks = TaskRegistry(queue_name="reports")


@tasks.task("reports.render")
async def render(task: Task, payload: dict) -> dict:
    return {"report_id": payload["report_id"], "attempt": task.attempt}


async def main() -> None:
    database_url = os.environ["PGTASK_DATABASE_URL"]
    client = await Client.connect(database_url)
    await client.migrate()
    await Worker(database_url, tasks).run()


asyncio.run(main())

Delivery is at least once, so write handlers that are safe to run again.

Enqueue a task

from __future__ import annotations

import asyncio
import os

from pgtask import Client, EnqueueRequest


async def main() -> None:
    client = await Client.connect(os.environ["PGTASK_DATABASE_URL"])
    handle = await client.enqueue(
        EnqueueRequest("reports.render", {"report_id": "report-123"}, queue_name="reports")
    )
    print(await handle.result(timeout=30.0))


asyncio.run(main())

Enqueue inside your transaction

This is the reason to keep the queue in the database. Pass your own connection and the task commits with your data or not at all. Roll back and the task never existed, which is what an outbox table is usually for.

async with connection.transaction():
    await connection.execute("INSERT INTO reports (id) VALUES (%s)", ("report-123",))
    await Client.enqueue_on(connection, request)

connection is your psycopg connection, not one of ours.

Documentation

kludex.github.io/pgtask covers workers, durable execution, signals, cancellation, scheduling, and OpenTelemetry propagation.

Metadata

Release files for pgtask 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pgtask 0.4.0
File Size Uploaded Provenance Actions
pgtask-0.4.0.tar.gz 239.3 kB With provenance Details for pgtask-0.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for pgtask 0.4.0
File Actions
pgtask-0.4.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for pgtask-0.4.0-cp310-abi3-win_amd64.whl
pgtask-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for pgtask-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl
pgtask-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for pgtask-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl
pgtask-0.4.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for pgtask-0.4.0-cp310-abi3-macosx_11_0_arm64.whl
pgtask-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for pgtask-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 21.8 MB

Release files / pgtask-0.4.0.tar.gz

Download URL pgtask-0.4.0.tar.gz
Size 239.3 kB
Tags Source
SHA-256 checksum
How to use checksums
6264fa78c75f3d0f169ecdd5b5ce08090c9393cce7eaa0e1c738f5818f3cd562
BLAKE2b-256 checksum
How to use checksums
7485645b268f8f6b15400b5a3baa4901e963703a870d19c0cdee5858918b726e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / pgtask-0.4.0-cp310-abi3-win_amd64.whl

Download URL pgtask-0.4.0-cp310-abi3-win_amd64.whl
Size 3.9 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
e094b497acdc8eac3a39fd39094e8b26b8a50a657b3baf16ec43e4e4669750d4
BLAKE2b-256 checksum
How to use checksums
a7b693767ff61a2cae27c0717c32c559eec066d368684161054e006d8d0471b7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / pgtask-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL pgtask-0.4.0-cp310-abi3-manylinux_2_28_x86_64.whl
Size 4.6 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
bb13b2980ae90054eeb87a76374fc7776fdac8b515eed70901576382f10e4e10
BLAKE2b-256 checksum
How to use checksums
ef6c1d86cf8c641340efd6c561a5367d443cd554cdf06c51f445582c4450bbe5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / pgtask-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL pgtask-0.4.0-cp310-abi3-manylinux_2_28_aarch64.whl
Size 4.6 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
4872defd7be392381899e1b5e9d640d46f99121d0c4e394acbef8b46c9bec7da
BLAKE2b-256 checksum
How to use checksums
0a8a662120bedf4ebb7adaecbf2b79bd31d0fa28ee4229a6e3733fea87b86b4f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / pgtask-0.4.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL pgtask-0.4.0-cp310-abi3-macosx_11_0_arm64.whl
Size 4.2 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
633536d8df80cff48eedb8b7ca987020d880033ba093fcf547d8beb29548507d
BLAKE2b-256 checksum
How to use checksums
15ccc429c63be8503e8d251e3f9dda24e502cb81003cfd086d5e24b459e5fcb7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / pgtask-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl

Download URL pgtask-0.4.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 4.3 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
6b0dbe2ff788ddb0dabaf3b378b8b15b7fe11d6980384daf0cae96207a6f23f7
BLAKE2b-256 checksum
How to use checksums
e8356888ba8ce26ff85a4242a10f67c7db7a9e2a04ab665fdf7ab5f02d2310c2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Security for pgtask 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for pgtask-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page