Getting Started

Install

Install the package and choose the right extras.

Published releases are available on PyPI and mirrored in GitHub Releases. These commands select the exact 0.1.0a41 release; do not let a package resolver substitute another prerelease.

pip install outlabs-taskq==0.1.0a41

# with extras:
pip install "outlabs-taskq[http]==0.1.0a41"
pip install "outlabs-taskq[outlabs]==0.1.0a41"

Requires Python 3.12+ and PostgreSQL 16+ (18 is the preferred deploy target).

Release a41 only changes the PostgreSQL 18 restore verifier. An existing a40 API, scheduler, or worker on SQL contract 0.6.12 does not need an immediate upgrade. For a PostgreSQL 18 dump/restore, use the a41 operator package for taskq db verify and follow the restore-verification procedure.

Dependency tiers

Install	What you get	Hard deps
`outlabs-taskq`	Migrator, models, asyncio SQL client, worker loop, CLI	pydantic, sqlalchemyasyncio, asyncpg, croniter
`[http]`	Facade app + HTTP clients + claim-wait hub	fastapi, httpx
`[outlabs]`	OutLabs queue authorizer + IAM provisioning	`[http]` + `outlabs-auth>=0.1.0a27,<0.2.0`

import taskq must succeed without FastAPI and without outlabs-auth.

Install the schema

Use the CLI (preferred) or call the migrator from your host migration tool. First create a secret-free named context as shown in the CLI reference, with the DSN supplied by its named environment variable:

taskq --context development db plan -o json
taskq --context development --yes db migrate --plan-digest "$PLAN_DIGEST"
taskq --context development db verify

For an existing database, do not migrate before every API, worker, scheduler, operator, migrator, and maintenance process is on a runtime that explicitly supports both the old and target contracts. Follow the runtime-first upgrade sequence.

On a fresh scheduler-capable database, the first apply intentionally stops after migration 0019 with code CLI_TARGET_BINDING_REQUIRED. Inspect target show, bind the installation with exact UUID/CAS values, then produce a fresh plan digest and resume. No command binds or migrates implicitly.

from taskq.sql import migrate_sync, verify_sync

def upgrade():
    # Alembic / host revision — run as a Postgres admin that can create roles
    migrate_sync(op.get_bind())
    report = verify_sync(op.get_bind())
    assert report.ok

There is no install() helper. db migrate applies packaged SQL (0001–0048) under an advisory lock; verify is the read-only drift oracle (catalog, grants, checksums) for SQL contract 0.6.12. Run both with an administrative deployment credential, not a runtime capability role.

Capability roles

The installer creates six roles (ADR-010):

Role	Purpose
`taskq_owner`	Owns schema objects
`taskq_producer`	Enqueue
`taskq_runner`	Claim / heartbeat / settle
`taskq_observer`	Stats / read views
`taskq_operator`	Redrive / cancel / control
`taskq_housekeeper`	Tick / reaper

Host apps call migrate / verify — do not fork the SQL in-tree. Programmatic migration still obeys the same target-binding gate.

Introduction

What OutlabsTaskq is, and what problems it is built to solve.

Quickstart

Migrate, register a task, enqueue, and run a worker.