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..78dbe2f9 100644 --- a/website/docs/library/add-job.md +++ b/website/docs/library/add-job.md @@ -42,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 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`).