Skip to content

Horsies

PostgreSQL-backed background task queue and workflow engine for Python.

Most businesses need durable, observable systems with strong execution guarantees. Traditional queues do not give you that out of the box. You end up writing tedious state machines around them, and your execution state gets mixed into your business logic, because your execution layer was never durable.

Horsies lets you declare your conditional business logic as tasks and workflows, without managing execution state on top of it.

Using Rust? The Rust docs cover the horsies crate. The Python and Rust libraries have almost the same API and mental model, but they are not interoperable.

The tasks view of the Horsies web UI: status counts, error codes by category, filters and live task rowsThe tasks view of the Horsies web UI: status counts, error codes by category, filters and live task rows
The live state and the history of your tasks, with errors grouped by their code families.
The failed tasks with their error codes, and one task opened to its UNHANDLED_EXCEPTION error and attempt historyThe failed tasks with their error codes, and one task opened to its UNHANDLED_EXCEPTION error and attempt history
A task opens down to each attempt: which worker ran it, when, and what came back.
A completed order_fulfillment workflow run shown as its graph of ten nodesA completed order_fulfillment workflow run shown as its graph of ten nodes
A workflow run opens as its graph.
The shipping node of the workflow run opened as its child workflow of three nodes, next to the parent graphThe shipping node of the workflow run opened as its child workflow of three nodes, next to the parent graph
A child workflow opens inside its parent run.
The workers view of the Horsies web UI: database health, a worker card, schedules, and load and CPU charts over timeThe workers view of the Horsies web UI: database health, a worker card, schedules, and load and CPU charts over time
Your workers and schedules, with the load on each worker over time.
from pydantic import SecretStr
from horsies import Horsies, AppConfig, PostgresConfig, TaskResult, TaskError, Ok, Err
app = Horsies(AppConfig(
broker=PostgresConfig(
database_url=SecretStr("postgresql+psycopg://user:pass@localhost:5432/mydb"),
),
))
@app.task("add_numbers")
def add_numbers(*, a: int, b: int) -> TaskResult[int, TaskError]:
return TaskResult(ok=a + b)
# Send and get result
match add_numbers.send(a=5, b=3):
case Ok(handle):
result = handle.get()
if result.is_ok():
print(result.ok_value) # 8
case Err(send_err):
print(f"Send failed: {send_err.code} - {send_err.message}")

llms.txt lists every page of these docs with keywords. The package ships a skill folder for coding agents; copy it with horsies skills install --target DIR.