Configuring Horsies

Prerequisites

• PostgreSQL 12+
• Python 3.13+

Installation

uv add horsies

Basic Configuration

from horsies import Horsies, AppConfig, PostgresConfig

config = AppConfig(
    broker=PostgresConfig(
        database_url="postgresql+psycopg://user:password@localhost:5432/mydb",
    ),
)

app = Horsies(config)

Custom Queues with Priorities

Different operations have different urgency levels can be defined with priority values. 1-100 where 1 is priority numero uno.

from horsies import Horsies, AppConfig, PostgresConfig, QueueMode, CustomQueueConfig

config = AppConfig(
    queue_mode=QueueMode.CUSTOM,
    custom_queues=[
        CustomQueueConfig(name="urgent", priority=1, max_concurrency=10),
        CustomQueueConfig(name="standard", priority=50, max_concurrency=20),
        CustomQueueConfig(name="low", priority=100, max_concurrency=5),
    ],
    broker=PostgresConfig(
        database_url="postgresql+psycopg://user:password@localhost:5432/db_name",
    ),
)

app = Horsies(config) # use this app instance for decorating task

Queue	Priority	Use Case
urgent	1	The most important queue
standard	50	Things in between
low	100	The least important, can wait

Task Discovery

app.discover_tasks([
    "myapp.tasks",
    "myapp.workflows",
])

discover_tasks records module paths for later import by the worker. Dotted module paths use importlib.import_module(), while .py entries are imported by file path — it does not recursively scan submodules.

To discover tasks in myapp.tasks.scraping, either list it explicitly:

app.discover_tasks([
    "myapp.tasks",
    "myapp.tasks.scraping",
    "myapp.workflows",
])

Or export the decorated functions from myapp.tasks.__init__.py so importing myapp.tasks triggers the decorator registration.

Running the Worker

horsies worker myapp.config:app --processes=8 --loglevel=INFO