From 7efd9b883f01ae9aed031fd9be149bda5f743807 Mon Sep 17 00:00:00 2001 From: Ben Limmer Date: Wed, 13 Aug 2025 11:05:59 -0600 Subject: [PATCH 1/2] docs: improve queueName docs to avoid high cardinality --- src/interfaces.ts | 12 +++++++++--- website/docs/library/add-job.md | 13 +++++++++++++ website/docs/library/add-jobs.md | 4 +++- website/docs/sql-add-job.md | 4 +++- 4 files changed, 28 insertions(+), 5 deletions(-) diff --git a/src/interfaces.ts b/src/interfaces.ts index 44cd73d9..9467193d 100644 --- a/src/interfaces.ts +++ b/src/interfaces.ts @@ -84,7 +84,9 @@ export interface AddJobsJobSpec< /** * The queue to run this task under (only specify if you want jobs in this - * queue to run serially). (Default: null) + * queue to run serially). Avoid using high cardinality values (e.g., random + * strings, UUIDs, timestamps) as this degrades performance and requires + * periodic database cleanup. (Default: null) */ queueName?: string; @@ -336,7 +338,9 @@ export interface CronItemOptions { /** Optionally override the default job max_attempts */ maxAttempts?: number; - /** Optionally set the job queue_name to enforce that the jobs run serially */ + /** Optionally set the job queue_name to enforce that the jobs run serially. + * Avoid using high cardinality values (e.g., random strings, UUIDs, timestamps) + * as this degrades performance and requires periodic database cleanup. */ queueName?: string; /** Optionally set the job priority */ @@ -586,7 +590,9 @@ export interface Cron { export interface TaskSpec { /** * The queue to run this task under (only specify if you want jobs in this - * queue to run serially). (Default: null) + * queue to run serially). Avoid using high cardinality values (e.g., random + * strings, UUIDs, timestamps) as this degrades performance and requires + * periodic database cleanup. (Default: null) */ queueName?: string; diff --git a/website/docs/library/add-job.md b/website/docs/library/add-job.md index 817068c4..3935f086 100644 --- a/website/docs/library/add-job.md +++ b/website/docs/library/add-job.md @@ -28,8 +28,21 @@ The `addJob` arguments are as follows: - `payload`: an optional JSON-compatible object to give the task more context on what it is doing, or a list of these objects in “batch job” mode - `options`: an optional object specifying: + - `queueName`: if you want certain jobs to run one at a time, add them to the same named queue (defaults to null which enables parallelization) + + :::warning + + Avoid using high cardinality values (e.g., random strings, UUIDs, + timestamps) for queue names as this will create many dead queues that + degrade performance and require + [periodic database cleanup](../admin-functions.md#gc_job_queues). If you + find yourself needing to run the `GC_JOB_QUEUES` cleanup task regularly, + you're likely using queue names incorrectly. + + ::: + - `runAt`: a `Date` to schedule this task to run in the future - `maxAttempts`: the maximum number of attempts we'll give the job (Default: 25) diff --git a/website/docs/library/add-jobs.md b/website/docs/library/add-jobs.md index 8c52c7c5..af2175f0 100644 --- a/website/docs/library/add-jobs.md +++ b/website/docs/library/add-jobs.md @@ -58,7 +58,9 @@ export interface AddJobsJobSpec { /** * The queue to run this task under (only specify if you want jobs in this - * queue to run serially). (Default: null) + * queue to run serially). Avoid using high cardinality values (e.g., random + * strings, UUIDs, timestamps) as this degrades performance and requires + * periodic database cleanup. (Default: null) */ queueName?: string; diff --git a/website/docs/sql-add-job.md b/website/docs/sql-add-job.md index 818179f2..1512989e 100644 --- a/website/docs/sql-add-job.md +++ b/website/docs/sql-add-job.md @@ -22,7 +22,9 @@ this underlying `add_job` SQL function. what to do, or an array of one or more of these objects for “batch jobs” (defaults to an empty object). - `queue_name` — if you want certain tasks to run one at a time, add them - to the same named queue (defaults to `null`). + to the same named queue. Avoid using high cardinality values (e.g., random + strings, UUIDs, timestamps) as this degrades performance and requires periodic + database cleanup (defaults to `null`). - `run_at` — a timestamp after which to run the job; defaults to now. - `max_attempts` — if this task fails, how many times should we retry it? (defaults to `25`. Must be castable to `smallint`). From 0042f00d6617a31fdc96e3ffcbda00b42f1103d3 Mon Sep 17 00:00:00 2001 From: Jem Gillam <6413628+jemgillam@users.noreply.github.com> Date: Fri, 15 Aug 2025 18:59:02 +0100 Subject: [PATCH 2/2] Move warning outside of bullet list --- website/docs/library/add-job.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/website/docs/library/add-job.md b/website/docs/library/add-job.md index 3935f086..78dbe2f9 100644 --- a/website/docs/library/add-job.md +++ b/website/docs/library/add-job.md @@ -28,21 +28,8 @@ The `addJob` arguments are as follows: - `payload`: an optional JSON-compatible object to give the task more context on what it is doing, or a list of these objects in “batch job” mode - `options`: an optional object specifying: - - `queueName`: if you want certain jobs to run one at a time, add them to the same named queue (defaults to null which enables parallelization) - - :::warning - - Avoid using high cardinality values (e.g., random strings, UUIDs, - timestamps) for queue names as this will create many dead queues that - degrade performance and require - [periodic database cleanup](../admin-functions.md#gc_job_queues). If you - find yourself needing to run the `GC_JOB_QUEUES` cleanup task regularly, - you're likely using queue names incorrectly. - - ::: - - `runAt`: a `Date` to schedule this task to run in the future - `maxAttempts`: the maximum number of attempts we'll give the job (Default: 25) @@ -55,6 +42,16 @@ The `addJob` arguments are as follows: (see [Replacing and updating jobs](../job-key.md#replacingupdating-jobs) and [removing jobs](../job-key.md#removing-jobs)) +:::warning Avoid high cardinality in queue names + +Avoid using high cardinality values (e.g., random strings, UUIDs, timestamps) +for queue names as this will create many dead queues that degrade performance +and require [periodic database cleanup](../admin-functions.md#gc_job_queues). If +you find yourself needing to run the `GC_JOB_QUEUES` cleanup task regularly, +you're likely using queue names incorrectly. + +::: + Example: ```js