Soniq class reference¶

The Soniq class is the central object in Soniq, a Python background-job library that stores jobs in PostgreSQL. An instance owns one database connection pool, one job registry and one set of settings. You can run several independent instances in the same process.

Constructor¶

from soniq import Soniq

soniq = Soniq(
    database_url="postgresql://localhost/myapp",
    backend=None,
    retry_policy=None,
    metrics_sink=None,
    plugins=None,
    autoload_plugins=False,
    **settings_overrides,
)

You can read soniq.retry_policy and soniq.metrics_sink, and assign new values to them. Assigning after the instance is initialized raises SoniqError with code SONIQ_APP_FROZEN.

Settings¶

Pass a setting as a keyword argument, or set the matching SONIQ_* environment variable. Soniq validates every value when the instance is created.

max_retries applies only when you enqueue a job name that is not registered in the current process. A registered job uses its own retries.

Optional services¶

Optional features have no *_enabled flags. A feature is on when your code uses its property on the instance. Each property builds its service on first access and caches it.

await soniq.webhooks.register(url="https://...")      # webhooks
await soniq.dead_letter.list_dead_letter_jobs()       # dead-letter queue
await soniq.scheduler.add(my_job, cron="0 9 * * *")   # recurring schedules
soniq.signing.encrypt("plaintext")                    # Fernet encryption helpers
await soniq.logs.search_logs("error")                 # structured log queries

Other properties are soniq.settings, soniq.registry (the job registry), soniq.backend (None until the instance is initialized), soniq.is_initialized and soniq.is_closed.

The dashboard runs as its own process. Start it with soniq dashboard, or call create_dashboard_app(soniq). HTTP write actions need SONIQ_DASHBOARD_WRITE_ENABLED=true and SONIQ_DASHBOARD_API_KEY.

Lifecycle¶

The connection pool opens on first use, so most code needs no explicit init call. Call await soniq.ensure_initialized() when you need soniq.backend before the first enqueue.

close()¶

close() shuts down plugins in reverse install order, then closes the connection pool. A second call logs a warning and does nothing else.

await soniq.close()

Async context manager¶

async with initializes the instance on entry and calls close() on exit:

async with Soniq(database_url="postgresql://localhost/myapp") as soniq:
    await soniq.enqueue(my_job, message="hello")

setup()¶

applied = await soniq.setup()   # returns the number of migrations applied

setup() creates the database if it does not exist, runs the migrations and starts plugin on_startup hooks. This is the same work as the soniq setup command.

Acquiring a connection¶

Use a pooled connection when you need raw SQL next to an enqueue, as in transactional enqueue:

await soniq.ensure_initialized()
async with soniq.backend.acquire() as conn:
    async with conn.transaction():
        await conn.execute("INSERT INTO orders ...")
        await soniq.enqueue(send_receipt, connection=conn, order_id=42)

backend.acquire() is an async context manager. It lends a pooled connection and releases it on exit. Transactional enqueue needs the PostgreSQL backend.

get_queue_stats()¶

Returns one dictionary with job counts for the whole instance. It is not split by queue.

stats = await soniq.get_queue_stats()
# {"total": 150, "queued": 12, "processing": 3, "done": 130,
#  "dead_letter": 4, "cancelled": 1}

queued, processing, done and cancelled count rows in soniq_jobs. dead_letter counts rows in soniq_dead_letter_jobs. total is the sum of the five counts. When there are no jobs, every count is 0.

Job management methods¶

Each method takes a job_id string, which is the UUID that enqueue() returns. A string that is not a valid UUID raises ValueError on PostgreSQL.

To run a job again after it exhausted its retries, call soniq.dead_letter.replay(dead_letter_id). See the dead-letter API.

Configure Soniq with environment variables¶

Every setting has a SONIQ_* environment variable. Soniq resolves each value from the first source that sets it:

1. Keyword arguments passed to the constructor
2. Environment variables (SONIQ_*)
3. The .env file in the working directory
4. Default values

Example .env file:

SONIQ_DATABASE_URL=postgresql://user:pass@db.example.com/myapp
SONIQ_MAX_RETRIES=5
SONIQ_LOG_LEVEL=DEBUG

Next steps¶

• Jobs API - define, enqueue and schedule jobs.
• Worker API - run workers in a process.
• Hooks API - run code around every job.