pgtask 0.3.0__tar.gz → 0.4.0__tar.gz

{pgtask-0.3.0 → pgtask-0.4.0}/Cargo.lock

@@ -1195,7 +1195,7 @@ checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
 [[package]]
 name = "pgtask"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "pgtask-core",
  "pgtask-otel",
@@ -1208,7 +1208,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-bench"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "chrono",
  "pgtask",
@@ -1221,7 +1221,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-cli"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "clap",
  "pgtask",
@@ -1231,7 +1231,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-core"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "chrono",
  "cron",
@@ -1245,7 +1245,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-otel"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "opentelemetry",
  "opentelemetry_sdk",
@@ -1256,7 +1256,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-postgres"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "chrono",
  "pgtask-core",
@@ -1273,7 +1273,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-python"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "chrono",
  "pgtask",
@@ -1290,7 +1290,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-web"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "axum",
  "chrono",
@@ -1309,7 +1309,7 @@ dependencies = [
 
 [[package]]
 name = "pgtask-worker"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "axum",
  "chrono",
@@ -1674,9 +1674,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.43"
+version = "0.23.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0283386ce02abc0151e1761d08802dfe86c173b0b494af5cbc086574e453da06"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
 dependencies = [
  "once_cell",
  "ring",

{pgtask-0.3.0 → pgtask-0.4.0}/Cargo.toml

@@ -7,7 +7,7 @@ edition = "2024"
 license = "MIT"
 repository = "https://github.com/Kludex/pgtask"
 rust-version = "1.94"
-version = "0.3.0"
+version = "0.4.0"
 
 [workspace.dependencies]
 axum = "0.8.9"

{pgtask-0.3.0 → pgtask-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgtask
-Version: 0.3.0
+Version: 0.4.0
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10

{pgtask-0.3.0 → pgtask-0.4.0}/crates/pgtask/Cargo.toml

@@ -9,10 +9,10 @@ version.workspace = true
 readme = "README.md"
 
 [dependencies]
-pgtask-core = { path = "../pgtask-core", version = "0.3.0" }
-pgtask-otel = { path = "../pgtask-otel", version = "0.3.0" }
-pgtask-postgres = { path = "../pgtask-postgres", version = "0.3.0" }
-pgtask-worker = { path = "../pgtask-worker", version = "0.3.0" }
+pgtask-core = { path = "../pgtask-core", version = "0.4.0" }
+pgtask-otel = { path = "../pgtask-otel", version = "0.4.0" }
+pgtask-postgres = { path = "../pgtask-postgres", version = "0.4.0" }
+pgtask-worker = { path = "../pgtask-worker", version = "0.4.0" }
 
 [dev-dependencies]
 serde_json.workspace = true

{pgtask-0.3.0 → pgtask-0.4.0}/crates/pgtask-postgres/Cargo.toml

@@ -10,8 +10,8 @@ readme = "README.md"
 
 [dependencies]
 chrono.workspace = true
-pgtask-core = { path = "../pgtask-core", version = "0.3.0" }
-pgtask-otel = { path = "../pgtask-otel", version = "0.3.0" }
+pgtask-core = { path = "../pgtask-core", version = "0.4.0" }
+pgtask-otel = { path = "../pgtask-otel", version = "0.4.0" }
 serde_json.workspace = true
 sqlx.workspace = true
 thiserror.workspace = true

pgtask-0.4.0/crates/pgtask-postgres/migrations/0010_batch_task_transitions.sql

@@ -0,0 +1,189 @@
+CREATE FUNCTION pgtask.complete_tasks(p_completions jsonb)
+RETURNS TABLE(request_index bigint, completed boolean)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+BEGIN
+    IF p_completions IS NULL OR jsonb_typeof(p_completions) <> 'array' THEN
+        RAISE EXCEPTION 'completions must be a JSON array' USING ERRCODE = '22023';
+    END IF;
+    IF EXISTS (
+        SELECT 1
+        FROM jsonb_array_elements(p_completions) AS items(completion)
+        GROUP BY completion->>'task_id'
+        HAVING count(*) > 1
+    ) THEN
+        RAISE EXCEPTION 'completions contain duplicate task IDs' USING ERRCODE = '22023';
+    END IF;
+
+    RETURN QUERY
+    WITH requested AS (
+        SELECT
+            items.ordinality - 1 AS request_index,
+            (items.completion->>'task_id')::uuid AS task_id,
+            (items.completion->>'attempt')::integer AS attempt,
+            (items.completion->>'lease_token')::uuid AS lease_token,
+            CASE
+                WHEN (items.completion->>'has_result')::boolean THEN items.completion->'result'
+                ELSE NULL
+            END AS result
+        FROM jsonb_array_elements(p_completions) WITH ORDINALITY AS items(completion, ordinality)
+    ),
+    completed_tasks AS (
+        UPDATE pgtask.tasks
+        SET state = 'succeeded',
+            lease_token = NULL,
+            lease_owner = NULL,
+            lease_expires_at = NULL,
+            completed_at = statement_timestamp(),
+            updated_at = statement_timestamp(),
+            result = requested.result,
+            error = NULL
+        FROM requested
+        WHERE tasks.id = requested.task_id
+            AND tasks.state = 'running'
+            AND tasks.attempt = requested.attempt
+            AND tasks.lease_token = requested.lease_token
+        RETURNING requested.request_index, tasks.id, tasks.attempt
+    ),
+    completed_attempts AS (
+        UPDATE pgtask.attempts
+        SET state = 'succeeded', finished_at = statement_timestamp(), error = NULL
+        FROM completed_tasks
+        WHERE attempts.task_id = completed_tasks.id AND attempts.attempt = completed_tasks.attempt
+    )
+    SELECT requested.request_index, completed_tasks.id IS NOT NULL
+    FROM requested
+    LEFT JOIN completed_tasks USING (request_index)
+    ORDER BY requested.request_index;
+END;
+$$;
+
+CREATE FUNCTION pgtask.fail_tasks(p_failures jsonb)
+RETURNS TABLE(request_index bigint, state text)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+BEGIN
+    IF p_failures IS NULL OR jsonb_typeof(p_failures) <> 'array' THEN
+        RAISE EXCEPTION 'failures must be a JSON array' USING ERRCODE = '22023';
+    END IF;
+    IF EXISTS (
+        SELECT 1
+        FROM jsonb_array_elements(p_failures) AS items(failure)
+        GROUP BY failure->>'task_id'
+        HAVING count(*) > 1
+    ) THEN
+        RAISE EXCEPTION 'failures contain duplicate task IDs' USING ERRCODE = '22023';
+    END IF;
+
+    RETURN QUERY
+    WITH requested AS (
+        SELECT
+            items.ordinality - 1 AS request_index,
+            (items.failure->>'task_id')::uuid AS task_id,
+            (items.failure->>'attempt')::integer AS attempt,
+            (items.failure->>'lease_token')::uuid AS lease_token,
+            items.failure->'error' AS error,
+            (items.failure->>'retry_milliseconds')::bigint AS retry_milliseconds
+        FROM jsonb_array_elements(p_failures) WITH ORDINALITY AS items(failure, ordinality)
+    ),
+    failed_tasks AS (
+        UPDATE pgtask.tasks
+        SET state = CASE
+                WHEN requested.retry_milliseconds IS NOT NULL
+                    AND COALESCE(tasks.failed_attempts, (
+                        SELECT count(*)::integer FROM pgtask.attempts AS history
+                        WHERE history.task_id = tasks.id AND history.state IN ('failed', 'lost')
+                    )) + 1 < tasks.max_attempts THEN 'pending'
+                ELSE 'failed'
+            END,
+            run_at = CASE
+                WHEN requested.retry_milliseconds IS NOT NULL
+                    THEN statement_timestamp() + (requested.retry_milliseconds * interval '1 millisecond')
+                ELSE tasks.run_at
+            END,
+            lease_token = NULL,
+            lease_owner = NULL,
+            lease_expires_at = NULL,
+            completed_at = CASE
+                WHEN requested.retry_milliseconds IS NOT NULL
+                    AND COALESCE(tasks.failed_attempts, (
+                        SELECT count(*)::integer FROM pgtask.attempts AS history
+                        WHERE history.task_id = tasks.id AND history.state IN ('failed', 'lost')
+                    )) + 1 < tasks.max_attempts THEN NULL
+                ELSE statement_timestamp()
+            END,
+            updated_at = statement_timestamp(),
+            error = requested.error,
+            failed_attempts = COALESCE(tasks.failed_attempts, (
+                SELECT count(*)::integer FROM pgtask.attempts AS history
+                WHERE history.task_id = tasks.id AND history.state IN ('failed', 'lost')
+            )) + 1
+        FROM requested
+        WHERE tasks.id = requested.task_id
+            AND tasks.state = 'running'
+            AND tasks.attempt = requested.attempt
+            AND tasks.lease_token = requested.lease_token
+        RETURNING requested.request_index, tasks.id, tasks.attempt, tasks.state, requested.error
+    ),
+    failed_attempts AS (
+        UPDATE pgtask.attempts
+        SET state = 'failed', finished_at = statement_timestamp(), error = failed_tasks.error
+        FROM failed_tasks
+        WHERE attempts.task_id = failed_tasks.id AND attempts.attempt = failed_tasks.attempt
+    )
+    SELECT requested.request_index, failed_tasks.state
+    FROM requested
+    LEFT JOIN failed_tasks USING (request_index)
+    ORDER BY requested.request_index;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION pgtask.complete_tasks(jsonb) FROM PUBLIC;
+REVOKE ALL ON FUNCTION pgtask.fail_tasks(jsonb) FROM PUBLIC;
+
+DO $$
+DECLARE
+    definition text;
+    rewritten text;
+    target regrole;
+BEGIN
+    FOR target IN
+        SELECT privileges.grantee::regrole
+        FROM pg_proc
+        CROSS JOIN LATERAL aclexplode(pg_proc.proacl) AS privileges
+        WHERE pg_proc.oid = 'pgtask.complete_task(uuid, integer, uuid, jsonb)'::regprocedure
+            AND privileges.privilege_type = 'EXECUTE'
+    LOOP
+        EXECUTE format('GRANT EXECUTE ON FUNCTION pgtask.complete_tasks(jsonb) TO %s', target);
+    END LOOP;
+    FOR target IN
+        SELECT privileges.grantee::regrole
+        FROM pg_proc
+        CROSS JOIN LATERAL aclexplode(pg_proc.proacl) AS privileges
+        WHERE pg_proc.oid = 'pgtask.fail_task(uuid, integer, uuid, jsonb, bigint)'::regprocedure
+            AND privileges.privilege_type = 'EXECUTE'
+    LOOP
+        EXECUTE format('GRANT EXECUTE ON FUNCTION pgtask.fail_tasks(jsonb) TO %s', target);
+    END LOOP;
+
+    definition := pg_get_functiondef('pgtask.configure_grants(regrole, regrole, regrole, regrole, regrole)'::regprocedure);
+    rewritten := replace(
+        definition,
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.complete_task(uuid, integer, uuid, jsonb) TO %s'', p_worker);\n',
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.complete_task(uuid, integer, uuid, jsonb) TO %s'', p_worker);\n    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.complete_tasks(jsonb) TO %s'', p_worker);\n'
+    );
+    rewritten := replace(
+        rewritten,
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.fail_task(uuid, integer, uuid, jsonb, bigint) TO %s'', p_worker);\n',
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.fail_task(uuid, integer, uuid, jsonb, bigint) TO %s'', p_worker);\n    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.fail_tasks(jsonb) TO %s'', p_worker);\n'
+    );
+    IF rewritten = definition THEN
+        RAISE EXCEPTION 'could not extend pgtask.configure_grants';
+    END IF;
+    EXECUTE rewritten;
+END;
+$$;

pgtask-0.4.0/crates/pgtask-postgres/migrations/0011_null_idle_delays.sql

@@ -0,0 +1,79 @@
+-- The next_*_delay_milliseconds functions report how long a worker may sleep before the next
+-- deadline, and NULL when there is no deadline at all. Wrapping min() in GREATEST(0, ...) broke the
+-- NULL case: GREATEST ignores NULL arguments, so an empty set returned 0 and idle workers polled in
+-- a tight loop. Filtering the aggregate with HAVING keeps the 0 floor for overdue deadlines and
+-- returns no row, which a scalar SQL function reports as NULL, when nothing is due.
+--
+-- CREATE OR REPLACE keeps each function's owner and grants.
+
+CREATE OR REPLACE FUNCTION pgtask.next_schedule_delay_milliseconds()
+RETURNS bigint
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+    SELECT GREATEST(
+        0,
+        ceil(EXTRACT(epoch FROM (min(next_run_at) - statement_timestamp())) * 1000)::bigint
+    )
+    FROM pgtask.schedules
+    WHERE paused_at IS NULL
+    HAVING min(next_run_at) IS NOT NULL;
+$$;
+
+CREATE OR REPLACE FUNCTION pgtask.next_wait_delay_milliseconds()
+RETURNS bigint
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+    SELECT GREATEST(
+        0,
+        ceil(EXTRACT(epoch FROM (min(deadlines.timeout_at) - statement_timestamp())) * 1000)::bigint
+    )
+    FROM (
+        SELECT waits.timeout_at
+        FROM pgtask.waits
+        WHERE waits.resolved_at IS NULL AND waits.timeout_at IS NOT NULL
+        UNION ALL
+        SELECT result_waits.timeout_at
+        FROM pgtask.result_waits
+        WHERE result_waits.resolved_at IS NULL AND result_waits.timeout_at IS NOT NULL
+    ) AS deadlines
+    HAVING min(deadlines.timeout_at) IS NOT NULL;
+$$;
+
+CREATE OR REPLACE FUNCTION pgtask.next_task_delay_milliseconds(
+    p_queue_name text,
+    p_task_names text[],
+    p_handler_versions integer[]
+)
+RETURNS bigint
+LANGUAGE sql
+STABLE
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+    SELECT GREATEST(
+        0,
+        ceil(EXTRACT(epoch FROM (min(tasks.run_at) - statement_timestamp())) * 1000)::bigint
+    )
+    FROM pgtask.tasks
+    WHERE tasks.queue_name = p_queue_name
+        AND tasks.state = 'pending'
+        AND COALESCE(tasks.failed_attempts, (SELECT count(*)::integer FROM pgtask.attempts AS history WHERE history.task_id = tasks.id AND history.state IN ('failed', 'lost'))) < tasks.max_attempts
+        AND EXISTS (
+            SELECT 1
+            FROM pgtask.queues
+            WHERE queues.name = tasks.queue_name AND queues.paused_at IS NULL
+        )
+        AND EXISTS (
+            SELECT 1
+            FROM unnest(p_task_names, p_handler_versions) AS handlers(task_name, handler_version)
+            WHERE handlers.task_name = tasks.task_name
+                AND handlers.handler_version = tasks.handler_version
+        )
+    HAVING min(tasks.run_at) IS NOT NULL;
+$$;

pgtask-0.4.0/crates/pgtask-postgres/migrations/0013_resolve_waits_of_finished_tasks.sql

@@ -0,0 +1,81 @@
+-- A task that finishes while it waits for a signal (cancellation is the only way) used to keep its
+-- pgtask.waits row unresolved. When an administrator retried it, the handler replayed to the same
+-- wait_for_signal step and inserted the same key again, which failed on waits_pkey every attempt.
+--
+-- 1. Finishing a task resolves its open signal waits with outcome 'cancelled', in the trigger that
+--    already does this for its result waits, and existing leftovers are resolved the same way.
+-- 2. wait_for_signal and wait_for_result re-arm a wait row left over from an earlier attempt. They
+--    hold the task row lock and have just found no checkpoint for the step, so any row under that
+--    key is from an attempt that ended without the wait completing; a completed wait always writes
+--    its checkpoint in the same transaction that resolves the row.
+--
+-- The functions are rewritten from their installed definitions, so earlier rewrites are kept.
+
+ALTER TABLE pgtask.waits DROP CONSTRAINT waits_outcome_check;
+ALTER TABLE pgtask.waits
+    ADD CONSTRAINT waits_outcome_check CHECK (outcome IN ('signal', 'timeout', 'cancelled'));
+
+UPDATE pgtask.waits
+SET resolved_at = statement_timestamp(), outcome = 'cancelled'
+FROM pgtask.tasks
+WHERE waits.task_id = tasks.id
+    AND waits.resolved_at IS NULL
+    AND tasks.state IN ('succeeded', 'failed', 'cancelled');
+
+DO $$
+DECLARE
+    definition text;
+    rewritten text;
+BEGIN
+    definition := pg_get_functiondef('pgtask.resolve_task_result()'::regprocedure);
+    rewritten := replace(
+        definition,
+        E'    UPDATE pgtask.result_waits\n    SET resolved_at = statement_timestamp(), outcome = ''cancelled''\n    WHERE task_id = NEW.id AND resolved_at IS NULL;\n',
+        E'    UPDATE pgtask.result_waits\n    SET resolved_at = statement_timestamp(), outcome = ''cancelled''\n    WHERE task_id = NEW.id AND resolved_at IS NULL;\n\n'
+        || E'    UPDATE pgtask.waits\n    SET resolved_at = statement_timestamp(), outcome = ''cancelled''\n    WHERE task_id = NEW.id AND resolved_at IS NULL;\n'
+    );
+    IF rewritten = definition THEN
+        RAISE EXCEPTION 'could not extend pgtask.resolve_task_result';
+    END IF;
+    EXECUTE rewritten;
+
+    definition := pg_get_functiondef(
+        'pgtask.wait_for_signal(uuid, integer, uuid, text, integer, text, integer, bigint)'::regprocedure
+    );
+    rewritten := replace(
+        definition,
+        E'        p_task_id, target_handler_version, p_step_name, p_occurrence, p_signal_name, p_signal_occurrence, timeout_at\n    );\n',
+        E'        p_task_id, target_handler_version, p_step_name, p_occurrence, p_signal_name, p_signal_occurrence, timeout_at\n    )\n'
+        || E'    ON CONFLICT (task_id, handler_version, step_name, occurrence) DO UPDATE\n'
+        || E'    SET signal_name = EXCLUDED.signal_name,\n'
+        || E'        signal_occurrence = EXCLUDED.signal_occurrence,\n'
+        || E'        timeout_at = EXCLUDED.timeout_at,\n'
+        || E'        created_at = EXCLUDED.created_at,\n'
+        || E'        resolved_at = NULL,\n'
+        || E'        outcome = NULL;\n'
+    );
+    IF rewritten = definition THEN
+        RAISE EXCEPTION 'could not re-arm stale waits in pgtask.wait_for_signal';
+    END IF;
+    EXECUTE rewritten;
+
+    definition := pg_get_functiondef(
+        'pgtask.wait_for_result(uuid, integer, uuid, text, integer, uuid, bigint)'::regprocedure
+    );
+    rewritten := replace(
+        definition,
+        E'            ELSE statement_timestamp() + (p_timeout_milliseconds * interval ''1 millisecond'')\n        END\n    );\n',
+        E'            ELSE statement_timestamp() + (p_timeout_milliseconds * interval ''1 millisecond'')\n        END\n    )\n'
+        || E'    ON CONFLICT (task_id, handler_version, step_name, occurrence) DO UPDATE\n'
+        || E'    SET result_task_id = EXCLUDED.result_task_id,\n'
+        || E'        timeout_at = EXCLUDED.timeout_at,\n'
+        || E'        created_at = EXCLUDED.created_at,\n'
+        || E'        resolved_at = NULL,\n'
+        || E'        outcome = NULL;\n'
+    );
+    IF rewritten = definition THEN
+        RAISE EXCEPTION 'could not re-arm stale waits in pgtask.wait_for_result';
+    END IF;
+    EXECUTE rewritten;
+END;
+$$;

pgtask-0.4.0/crates/pgtask-postgres/migrations/0014_retention_throughput.sql

@@ -0,0 +1,139 @@
+-- Retention read every terminal task in a queue and sorted the expired ones to delete a batch of
+-- 100, and every deleted task cascaded into result_waits with a sequential scan, because the only
+-- index on result_waits.result_task_id is partial. Worker rows were never deleted at all.
+--
+-- On a large tasks table, building tasks_terminal_retention_idx blocks writes to tasks while it
+-- runs. To avoid that, create the same index with CREATE INDEX CONCURRENTLY before upgrading;
+-- IF NOT EXISTS then skips it here.
+
+CREATE INDEX IF NOT EXISTS tasks_terminal_retention_idx
+    ON pgtask.tasks (queue_name, completed_at, id)
+    WHERE state IN ('succeeded', 'failed', 'cancelled');
+
+-- The ON DELETE CASCADE from tasks looks rows up by result_task_id alone, resolved or not.
+CREATE INDEX IF NOT EXISTS result_waits_result_task_idx
+    ON pgtask.result_waits (result_task_id);
+
+-- Delete the locked candidates by tuple id instead of joining back on the key columns. CREATE OR
+-- REPLACE keeps each function's owner and grants; signatures and results are unchanged.
+
+CREATE OR REPLACE FUNCTION pgtask.delete_expired_terminal(p_queue_name text, p_limit integer)
+RETURNS bigint
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+    WITH candidates AS (
+        SELECT tasks.ctid AS tuple_id
+        FROM pgtask.tasks
+        WHERE tasks.queue_name = p_queue_name
+            AND tasks.state IN ('succeeded', 'failed', 'cancelled')
+            -- A scalar cutoff, not a join filter, so it bounds the index scan: a short final batch
+            -- stops at the first unexpired row instead of reading every terminal task in the queue.
+            AND tasks.completed_at <= (
+                SELECT statement_timestamp() - (queues.terminal_retention_seconds * interval '1 second')
+                FROM pgtask.queues
+                WHERE queues.name = p_queue_name
+            )
+            AND NOT EXISTS (
+                SELECT 1 FROM pgtask.tasks AS children WHERE children.parent_task_id = tasks.id
+            )
+        ORDER BY tasks.completed_at, tasks.id
+        FOR UPDATE OF tasks SKIP LOCKED
+        LIMIT p_limit
+    ),
+    deleted AS (
+        DELETE FROM pgtask.tasks
+        WHERE tasks.ctid = ANY (ARRAY(SELECT candidates.tuple_id FROM candidates))
+        RETURNING tasks.id
+    )
+    SELECT count(*) FROM deleted;
+$$;
+
+CREATE OR REPLACE FUNCTION pgtask.delete_expired_idempotency_keys(p_queue_name text, p_limit integer)
+RETURNS bigint
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+    WITH candidates AS (
+        SELECT idempotency_keys.ctid AS tuple_id
+        FROM pgtask.idempotency_keys
+        WHERE idempotency_keys.queue_name = p_queue_name
+            AND idempotency_keys.expires_at <= statement_timestamp()
+        ORDER BY idempotency_keys.expires_at, idempotency_keys.idempotency_key
+        FOR UPDATE SKIP LOCKED
+        LIMIT p_limit
+    ),
+    deleted AS (
+        DELETE FROM pgtask.idempotency_keys
+        WHERE idempotency_keys.ctid = ANY (ARRAY(SELECT candidates.tuple_id FROM candidates))
+        RETURNING idempotency_keys.idempotency_key
+    )
+    SELECT count(*) FROM deleted;
+$$;
+
+-- A worker row is inserted per process start and only ever expired. Delete rows that expired more
+-- than p_grace_milliseconds ago; worker_capabilities follows by cascade.
+CREATE FUNCTION pgtask.delete_expired_workers(p_grace_milliseconds bigint, p_limit integer)
+RETURNS bigint
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = pg_catalog, pgtask
+AS $$
+    WITH candidates AS (
+        SELECT workers.ctid AS tuple_id
+        FROM pgtask.workers
+        WHERE workers.expires_at <= statement_timestamp() - (p_grace_milliseconds * interval '1 millisecond')
+        ORDER BY workers.expires_at, workers.id
+        FOR UPDATE SKIP LOCKED
+        LIMIT p_limit
+    ),
+    deleted AS (
+        DELETE FROM pgtask.workers
+        WHERE workers.ctid = ANY (ARRAY(SELECT candidates.tuple_id FROM candidates))
+        RETURNING workers.id
+    )
+    SELECT count(*) FROM deleted;
+$$;
+
+REVOKE ALL ON FUNCTION pgtask.delete_expired_workers(bigint, integer) FROM PUBLIC;
+
+-- Grant it to every role that may already run retention, and teach configure_grants to do the same.
+DO $$
+DECLARE
+    definition text;
+    rewritten text;
+    target regrole;
+BEGIN
+    FOR target IN
+        SELECT privileges.grantee::regrole
+        FROM pg_proc
+        CROSS JOIN LATERAL aclexplode(pg_proc.proacl) AS privileges
+        WHERE pg_proc.oid = 'pgtask.delete_expired_terminal(text, integer)'::regprocedure
+            AND privileges.privilege_type = 'EXECUTE'
+    LOOP
+        EXECUTE format('GRANT EXECUTE ON FUNCTION pgtask.delete_expired_workers(bigint, integer) TO %s', target);
+    END LOOP;
+
+    definition := pg_get_functiondef('pgtask.configure_grants(regrole, regrole, regrole, regrole, regrole)'::regprocedure);
+    rewritten := replace(
+        definition,
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.delete_expired_terminal(text, integer) TO %s'', p_worker);\n',
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.delete_expired_terminal(text, integer) TO %s'', p_worker);\n'
+        || E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.delete_expired_workers(bigint, integer) TO %s'', p_worker);\n'
+    );
+    rewritten := replace(
+        rewritten,
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.delete_expired_terminal(text, integer) TO %s'', p_administrator);\n',
+        E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.delete_expired_terminal(text, integer) TO %s'', p_administrator);\n'
+        || E'    EXECUTE format(''GRANT EXECUTE ON FUNCTION pgtask.delete_expired_workers(bigint, integer) TO %s'', p_administrator);\n'
+    );
+    IF rewritten NOT LIKE '%delete_expired_workers(bigint, integer) TO %%s'', p_worker)%'
+        OR rewritten NOT LIKE '%delete_expired_workers(bigint, integer) TO %%s'', p_administrator)%'
+    THEN
+        RAISE EXCEPTION 'could not extend pgtask.configure_grants';
+    END IF;
+    EXECUTE rewritten;
+END;
+$$;