oban 0.5.0__py3-none-any.whl

oban/queries/ack_job.sql

@@ -0,0 +1,11 @@
+UPDATE oban_jobs
+SET state = %(state)s::oban_job_state,
+    cancelled_at = CASE WHEN %(state)s::oban_job_state = 'cancelled' THEN timezone('UTC', now()) ELSE cancelled_at END,
+    completed_at = CASE WHEN %(state)s::oban_job_state = 'completed' THEN timezone('UTC', now()) ELSE completed_at END,
+    discarded_at = CASE WHEN %(state)s::oban_job_state = 'discarded' THEN timezone('UTC', now()) ELSE discarded_at END,
+    scheduled_at = CASE WHEN %(schedule_in)s::int IS NULL THEN scheduled_at ELSE timezone('UTC', now()) + make_interval(secs => %(schedule_in)s::int) END,
+    attempt = COALESCE(%(attempt_change)s::int + attempt, attempt),
+    errors = CASE WHEN %(error)s::jsonb IS NULL THEN errors ELSE errors || %(error)s::jsonb END,
+    meta = CASE WHEN %(meta)s::jsonb IS NULL THEN meta ELSE meta || %(meta)s::jsonb END
+WHERE id = %(id)s
+RETURNING id;

oban/queries/all_jobs.sql

@@ -0,0 +1,25 @@
+SELECT
+  id,
+  state,
+  queue,
+  worker,
+  attempt,
+  max_attempts,
+  priority,
+  args,
+  meta,
+  errors,
+  tags,
+  attempted_by,
+  inserted_at,
+  attempted_at,
+  cancelled_at,
+  completed_at,
+  discarded_at,
+  scheduled_at
+FROM
+  oban_jobs
+WHERE
+  state = ANY(%(states)s)
+ORDER BY
+  id DESC

oban/queries/cancel_many_jobs.sql

@@ -0,0 +1,37 @@
+WITH locked_jobs AS (
+  SELECT
+    id, state
+  FROM
+    oban_jobs
+  WHERE
+    id = ANY(%(ids)s)
+    AND state IN ('executing', 'available', 'scheduled', 'retryable', 'suspended')
+  FOR UPDATE
+),
+updated_jobs AS (
+  UPDATE
+    oban_jobs oj
+  SET
+    state = CASE
+      WHEN oj.state = 'executing' THEN oj.state
+      ELSE 'cancelled'::oban_job_state
+    END,
+    cancelled_at = CASE
+      WHEN oj.state = 'executing' THEN oj.cancelled_at
+      ELSE timezone('UTC', now())
+    END,
+    meta = CASE
+      WHEN oj.state = 'executing' THEN oj.meta
+      ELSE oj.meta || jsonb_build_object('cancel_attempted_at', timezone('UTC', now()))
+    END
+  FROM
+    locked_jobs
+  WHERE
+    oj.id = locked_jobs.id
+  RETURNING
+    oj.id, locked_jobs.state AS original_state
+)
+SELECT
+  id, original_state
+FROM
+  updated_jobs

oban/queries/cleanup_expired_leaders.sql

@@ -0,0 +1,4 @@
+DELETE FROM
+  oban_leaders
+WHERE
+  expires_at < timezone('UTC', now())

oban/queries/cleanup_expired_producers.sql

@@ -0,0 +1,2 @@
+DELETE FROM oban_producers
+WHERE updated_at < timezone('UTC', now()) - make_interval(secs => %(max_age)s)

oban/queries/delete_many_jobs.sql

@@ -0,0 +1,5 @@
+DELETE FROM
+  oban_jobs
+WHERE
+  id = ANY(%(ids)s)
+  AND state != 'executing'

oban/queries/delete_producer.sql

@@ -0,0 +1,2 @@
+DELETE FROM oban_producers
+WHERE uuid = %(uuid)s

oban/queries/elect_leader.sql

@@ -0,0 +1,10 @@
+INSERT INTO oban_leaders (
+  name, node, elected_at, expires_at
+) VALUES (
+  %(name)s,
+  %(node)s,
+  timezone('UTC', now()),
+  timezone('UTC', now()) + interval '%(ttl)s seconds'
+)
+ON CONFLICT (name) DO NOTHING
+RETURNING node

oban/queries/fetch_jobs.sql

@@ -0,0 +1,44 @@
+WITH locked_jobs AS (
+  SELECT
+    priority, scheduled_at, id
+  FROM
+  oban_jobs
+  WHERE
+    state = 'available'
+    AND queue = %(queue)s
+  ORDER BY
+    priority ASC, scheduled_at ASC, id ASC
+  LIMIT
+    %(demand)s
+  FOR UPDATE SKIP LOCKED
+)
+UPDATE
+  oban_jobs oj
+SET
+  attempt = oj.attempt + 1,
+  attempted_at = timezone('UTC', now()),
+  attempted_by = %(attempted_by)s,
+  state = 'executing'
+FROM
+  locked_jobs
+WHERE
+  oj.id = locked_jobs.id
+RETURNING
+  oj.id,
+  oj.state,
+  oj.queue,
+  oj.worker,
+  oj.attempt,
+  oj.max_attempts,
+  oj.priority,
+  oj.args,
+  oj.meta,
+  oj.errors,
+  oj.tags,
+  oj.attempted_by,
+  oj.inserted_at,
+  oj.attempted_at,
+  oj.cancelled_at,
+  oj.completed_at,
+  oj.discarded_at,
+  oj.scheduled_at

oban/queries/get_job.sql

@@ -0,0 +1,23 @@
+SELECT
+  id,
+  state,
+  queue,
+  worker,
+  attempt,
+  max_attempts,
+  priority,
+  args,
+  meta,
+  errors,
+  tags,
+  attempted_by,
+  inserted_at,
+  attempted_at,
+  cancelled_at,
+  completed_at,
+  discarded_at,
+  scheduled_at
+FROM
+  oban_jobs
+WHERE
+  id = %s

oban/queries/insert_job.sql

@@ -0,0 +1,28 @@
+INSERT INTO oban_jobs(
+    args,
+    inserted_at,
+    max_attempts,
+    meta,
+    priority,
+    queue,
+    scheduled_at,
+    state,
+    tags,
+    worker
+) VALUES (
+    %(args)s,
+    coalesce(%(inserted_at)s, timezone('UTC', now())),
+    %(max_attempts)s,
+    %(meta)s,
+    %(priority)s,
+    %(queue)s,
+    coalesce(%(scheduled_at)s, timezone('UTC', now())),
+    CASE
+        WHEN %(state)s = 'available' AND %(scheduled_at)s IS NOT NULL
+        THEN 'scheduled'::oban_job_state
+        ELSE %(state)s::oban_job_state
+    END,
+    %(tags)s,
+    %(worker)s
+)
+RETURNING id, inserted_at, queue, scheduled_at, state;

oban/queries/insert_producer.sql

@@ -0,0 +1,2 @@
+INSERT INTO oban_producers (uuid, name, node, queue, meta)
+VALUES (%(uuid)s, %(name)s, %(node)s, %(queue)s, %(meta)s)

oban/queries/install.sql

@@ -0,0 +1,113 @@
+-- Types
+
+DO $$
+BEGIN
+    IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'oban_job_state') THEN
+        CREATE TYPE oban_job_state AS ENUM (
+            'available',
+            'scheduled',
+            'suspended',
+            'executing',
+            'retryable',
+            'completed',
+            'discarded',
+            'cancelled'
+        );
+    END IF;
+END
+$$;
+
+-- Tables
+
+CREATE TABLE IF NOT EXISTS oban_jobs (
+    id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
+    state oban_job_state NOT NULL DEFAULT 'available',
+    queue text NOT NULL DEFAULT 'default',
+    worker text NOT NULL,
+    attempt smallint NOT NULL DEFAULT 0,
+    max_attempts smallint NOT NULL DEFAULT 20,
+    priority smallint NOT NULL DEFAULT 0,
+    args jsonb NOT NULL DEFAULT '{}',
+    meta jsonb NOT NULL DEFAULT '{}',
+    tags jsonb NOT NULL DEFAULT '[]',
+    errors jsonb NOT NULL DEFAULT '[]',
+    attempted_by text[] NOT NULL DEFAULT ARRAY[]::TEXT[],
+    inserted_at timestamp WITHOUT TIME ZONE NOT NULL DEFAULT timezone('UTC', now()),
+    scheduled_at timestamp WITHOUT TIME ZONE NOT NULL DEFAULT timezone('UTC', now()),
+    attempted_at timestamp WITHOUT TIME ZONE,
+    cancelled_at timestamp WITHOUT TIME ZONE,
+    completed_at timestamp WITHOUT TIME ZONE,
+    discarded_at timestamp WITHOUT TIME ZONE,
+
+    CONSTRAINT attempt_range CHECK (attempt >= 0 AND attempt <= max_attempts),
+    CONSTRAINT queue_length CHECK (char_length(queue) > 0),
+    CONSTRAINT worker_length CHECK (char_length(worker) > 0),
+    CONSTRAINT positive_max_attempts CHECK (max_attempts > 0),
+    CONSTRAINT non_negative_priority CHECK (priority >= 0)
+);
+
+CREATE UNLOGGED TABLE IF NOT EXISTS oban_leaders (
+    name text PRIMARY KEY DEFAULT 'oban',
+    node text NOT NULL,
+    elected_at timestamp WITHOUT TIME ZONE NOT NULL,
+    expires_at timestamp WITHOUT TIME ZONE NOT NULL
+);
+
+CREATE UNLOGGED TABLE IF NOT EXISTS oban_producers (
+    uuid uuid PRIMARY KEY,
+    name text NOT NULL DEFAULT 'oban',
+    node text NOT NULL,
+    queue text NOT NULL,
+    meta jsonb NOT NULL DEFAULT '{}',
+    started_at timestamp WITHOUT TIME ZONE NOT NULL DEFAULT timezone('UTC', now()),
+    updated_at timestamp WITHOUT TIME ZONE NOT NULL DEFAULT timezone('UTC', now())
+);
+
+-- Indexes
+
+CREATE INDEX IF NOT EXISTS oban_jobs_state_queue_priority_scheduled_at_id_index
+ON oban_jobs (state, queue, priority, scheduled_at, id)
+WITH (fillfactor = 90);
+
+CREATE INDEX IF NOT EXISTS oban_jobs_staging_index
+ON oban_jobs (scheduled_at, id)
+WHERE state IN ('scheduled', 'retryable');
+
+CREATE INDEX IF NOT EXISTS oban_jobs_completed_at_index
+ON oban_jobs (completed_at)
+WHERE state = 'completed';
+
+CREATE INDEX IF NOT EXISTS oban_jobs_cancelled_at_index
+ON oban_jobs (cancelled_at)
+WHERE state = 'cancelled';
+
+CREATE INDEX IF NOT EXISTS oban_jobs_discarded_at_index
+ON oban_jobs (discarded_at)
+WHERE state = 'discarded';
+
+-- Autovacuum
+
+ALTER TABLE oban_jobs SET (
+  -- Vacuum earlier on large tables
+  autovacuum_vacuum_scale_factor = 0.02,
+  autovacuum_vacuum_threshold = 50,
+
+  -- Keep stats fresh for the planner
+  autovacuum_analyze_scale_factor = 0.02,
+  autovacuum_analyze_threshold = 100,
+
+  -- Make autovacuum push harder with little/no sleeping
+  autovacuum_vacuum_cost_limit = 2000,
+  autovacuum_vacuum_cost_delay = 1,
+
+  -- Handle insert-heavy spikes (PG13+)
+  autovacuum_vacuum_insert_scale_factor = 0.02,
+  autovacuum_vacuum_insert_threshold = 1000,
+
+  -- Leave headroom on pages for locality and fewer page splits
+  fillfactor = 85
+);
+
+-- Version
+
+COMMENT ON TABLE oban_jobs IS '1';

oban/queries/prune_jobs.sql

@@ -0,0 +1,18 @@
+WITH jobs_to_delete AS (
+  SELECT
+    id
+  FROM
+    oban_jobs
+  WHERE
+    (state = 'completed' AND completed_at <= timezone('UTC', now()) - make_interval(secs => %(max_age)s)) OR
+    (state = 'cancelled' AND cancelled_at <= timezone('UTC', now()) - make_interval(secs => %(max_age)s)) OR
+    (state = 'discarded' AND discarded_at <= timezone('UTC', now()) - make_interval(secs => %(max_age)s))
+  ORDER BY
+    id ASC
+  LIMIT
+    %(limit)s
+)
+DELETE FROM
+  oban_jobs
+WHERE
+  id IN (SELECT id FROM jobs_to_delete)

oban/queries/reelect_leader.sql

@@ -0,0 +1,12 @@
+INSERT INTO oban_leaders (name, node, elected_at, expires_at)
+VALUES (
+  %(name)s,
+  %(node)s,
+  timezone('UTC', now()),
+  timezone('UTC', now()) + interval '%(ttl)s seconds'
+)
+ON CONFLICT (name) DO UPDATE SET
+  expires_at = EXCLUDED.expires_at
+WHERE
+  oban_leaders.node = EXCLUDED.node
+RETURNING node

oban/queries/refresh_producers.sql

@@ -0,0 +1,3 @@
+UPDATE oban_producers
+SET updated_at = timezone('UTC', now())
+WHERE uuid = ANY(%(uuids)s)

oban/queries/rescue_jobs.sql

@@ -0,0 +1,18 @@
+UPDATE
+  oban_jobs
+SET
+  state = CASE
+    WHEN attempt >= max_attempts THEN 'discarded'::oban_job_state
+    ELSE 'available'::oban_job_state
+  END,
+  discarded_at = CASE
+    WHEN attempt >= max_attempts THEN timezone('UTC', now())
+    ELSE discarded_at
+  END,
+  meta = CASE
+    WHEN attempt >= max_attempts THEN meta
+    ELSE meta || jsonb_build_object('rescued', coalesce((meta->>'rescued')::int, 0) + 1)
+  END
+WHERE
+  state = 'executing'
+  AND attempted_at < timezone('UTC', now()) - make_interval(secs => %(rescue_after)s)

oban/queries/reset.sql

@@ -0,0 +1,5 @@
+TRUNCATE TABLE
+  oban_jobs,
+  oban_leaders,
+  oban_producers
+RESTART IDENTITY CASCADE

oban/queries/resign_leader.sql

@@ -0,0 +1,4 @@
+DELETE FROM
+  oban_leaders
+WHERE
+  name = %(name)s AND node = %(node)s

oban/queries/retry_many_jobs.sql

@@ -0,0 +1,13 @@
+UPDATE
+  oban_jobs
+SET
+  state = 'available'::oban_job_state,
+  max_attempts = GREATEST(max_attempts, attempt + 1),
+  scheduled_at = timezone('UTC', now()),
+  completed_at = NULL,
+  cancelled_at = NULL,
+  discarded_at = NULL,
+  meta = jsonb_set(meta, '{uniq_bmp}', '[]'::jsonb)
+WHERE
+  id = ANY(%(ids)s)
+  AND state NOT IN ('available', 'executing')

oban/queries/stage_jobs.sql

@@ -0,0 +1,34 @@
+WITH locked_jobs AS (
+  SELECT
+    id
+  FROM
+    oban_jobs
+  WHERE
+    state = ANY('{scheduled,retryable}')
+    AND scheduled_at <= coalesce(%(before)s, timezone('UTC', now()))
+  ORDER BY
+    scheduled_at ASC, id ASC
+  LIMIT
+    %(limit)s
+  FOR UPDATE SKIP LOCKED
+),
+updated_jobs AS (
+  UPDATE
+    oban_jobs
+  SET
+    state = 'available'::oban_job_state
+  FROM
+    locked_jobs
+  WHERE
+    oban_jobs.id = locked_jobs.id
+)
+SELECT DISTINCT
+  q.queue
+FROM
+  unnest(%(queues)s::text[]) AS q(queue)
+WHERE
+  EXISTS (
+    SELECT 1
+    FROM oban_jobs
+    WHERE state = 'available' AND queue = q.queue
+  )

oban/queries/uninstall.sql

@@ -0,0 +1,4 @@
+DROP TABLE IF EXISTS oban_producers CASCADE;
+DROP TABLE IF EXISTS oban_leaders CASCADE;
+DROP TABLE IF EXISTS oban_jobs CASCADE;
+DROP TYPE IF EXISTS oban_job_state CASCADE;

oban/queries/update_job.sql

@@ -0,0 +1,54 @@
+WITH raw_job_data AS (
+    SELECT
+        unnest(%(ids)s::bigint[]) AS id,
+        unnest(%(args)s::jsonb[]) AS args,
+        unnest(%(max_attempts)s::smallint[]) AS max_attempts,
+        unnest(%(meta)s::jsonb[]) AS meta,
+        unnest(%(priority)s::smallint[]) AS priority,
+        unnest(%(queue)s::text[]) AS queue,
+        unnest(%(scheduled_at)s::timestamptz[]) AS scheduled_at,
+        unnest(%(tags)s::jsonb[]) AS tags,
+        unnest(%(worker)s::text[]) AS worker
+),
+locked_jobs AS (
+  SELECT
+    id
+  FROM
+    oban_jobs
+  WHERE
+    id = ANY(%(ids)s)
+  FOR UPDATE
+)
+UPDATE
+  oban_jobs oj
+SET
+  args = rjd.args,
+  max_attempts = rjd.max_attempts,
+  meta = rjd.meta,
+  priority = rjd.priority,
+  queue = rjd.queue,
+  scheduled_at = rjd.scheduled_at,
+  state = CASE
+    WHEN oj.state = 'available' AND rjd.scheduled_at > timezone('UTC', now())
+    THEN 'scheduled'::oban_job_state
+    WHEN oj.state = 'scheduled' AND rjd.scheduled_at <= timezone('UTC', now())
+    THEN 'available'::oban_job_state
+    ELSE oj.state
+  END,
+  tags = rjd.tags,
+  worker = rjd.worker
+FROM
+  raw_job_data rjd
+  INNER JOIN locked_jobs lj ON rjd.id = lj.id
+WHERE
+  oj.id = rjd.id
+RETURNING
+  oj.args,
+  oj.max_attempts,
+  oj.meta,
+  oj.priority,
+  oj.queue,
+  oj.scheduled_at,
+  oj.state,
+  oj.tags,
+  oj.worker;

oban/queries/update_producer.sql

@@ -0,0 +1,3 @@
+UPDATE oban_producers
+SET meta = meta || %(meta)s
+WHERE uuid = %(uuid)s

oban/queries/verify_structure.sql

@@ -0,0 +1,9 @@
+SELECT
+  table_name
+FROM
+  information_schema.tables
+WHERE
+  table_schema = %(prefix)s
+  AND table_name = ANY('{oban_jobs,oban_leaders,oban_producers}')
+ORDER BY
+  table_name

oban/schema.py

@@ -0,0 +1,115 @@
+"""Database schema installation for Oban."""
+
+from typing import Any
+
+from ._query import Query
+
+INITIAL_VERSION = 1
+CURRENT_VERSION = 1
+
+
+def install_sql(prefix: str = "public") -> str:
+    """Get the SQL for installing Oban.
+
+    Returns the raw SQL statements for creating Oban types, tables, and indexes.
+    This is intended for integration with migration frameworks like Django or Alembic.
+
+    Args:
+        prefix: PostgreSQL schema where Oban tables will be located (default: "public")
+
+    Returns:
+        SQL string for schema installation
+
+    Example (Alembic):
+        >>> from alembic import op
+        >>> from oban.schema import install_sql
+        >>>
+        >>> def upgrade():
+        ...     op.execute(install_sql())
+
+    Example (Django):
+        >>> from django.db import migrations
+        >>> from oban.schema import install_sql
+        >>>
+        >>> class Migration(migrations.Migration):
+        ...     operations = [
+        ...         migrations.RunSQL(install_sql()),
+        ...     ]
+    """
+    return Query._load_file("install.sql", prefix)
+
+
+def uninstall_sql(prefix: str = "public") -> str:
+    """Get the SQL for uninstalling Oban.
+
+    Returns the raw SQL statements for dropping Oban tables and types.
+    Useful for integration with migration frameworks like Alembic or Django.
+
+    Args:
+        prefix: PostgreSQL schema where Oban tables are located (default: "public")
+
+    Returns:
+        SQL string for schema uninstallation
+
+    Example (Alembic):
+        >>> from alembic import op
+        >>> from oban.schema import uninstall_sql
+        >>>
+        >>> def downgrade():
+        ...     op.execute(uninstall_sql())
+
+    Example (Django):
+        >>> from django.db import migrations
+        >>> from oban.schema import uninstall_sql
+        >>>
+        >>> class Migration(migrations.Migration):
+        ...     operations = [
+        ...         migrations.RunSQL(uninstall_sql()),
+        ...     ]
+    """
+    return Query._load_file("uninstall.sql", prefix)
+
+
+async def install(pool: Any, prefix: str = "public") -> None:
+    """Install Oban in the specified database.
+
+    Creates all necessary types, tables, and indexes for Oban to function. The
+    installation is wrapped in a DDL transaction to ensure the operation is
+    atomic.
+
+    Args:
+        pool: A database connection pool (e.g., AsyncConnectionPool)
+        prefix: PostgreSQL schema where Oban tables will be located (default: "public")
+
+    Example:
+        >>> from psycopg_pool import AsyncConnectionPool
+        >>> from oban.schema import install
+        >>>
+        >>> pool = AsyncConnectionPool(conninfo=DATABASE_URL, open=False)
+        >>> await pool.open()
+        >>> await install(pool)
+    """
+    async with pool.connection() as conn:
+        await conn.execute(install_sql(prefix))
+
+
+async def uninstall(pool: Any, prefix: str = "public") -> None:
+    """Uninstall Oban from the specified database.
+
+    Drops all Oban tables and types. The uninstallation is wrapped in a DDL
+    transaction to ensure the operation is atomic.
+
+    Args:
+        pool: A database connection pool (e.g., AsyncConnectionPool)
+        prefix: PostgreSQL schema where Oban tables are located (default: "public")
+
+    Example:
+        >>> from psycopg_pool import AsyncConnectionPool
+        >>> from oban.schema import uninstall
+        >>>
+        >>> pool = AsyncConnectionPool(conninfo=DATABASE_URL, open=False)
+        >>> await pool.open()
+        >>> await uninstall(pool)
+    """
+    async with pool.connection() as conn:
+        await conn.execute(uninstall_sql(prefix))

oban/telemetry/__init__.py

@@ -0,0 +1,10 @@
+"""
+Lightweight telemetry tooling for agnostic instrumentation.
+
+Provides event emission and handler attachment for instrumentation,
+similar to Elixir's `:telemetry` library, but tailored to Oban's needs.
+"""
+
+from .core import Collector, attach, detach, execute, span
+
+__all__ = ["Collector", "attach", "detach", "execute", "span"]