docs: improve queueName docs to avoid high cardinality (#558)

Author: benjie

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;
 

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

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;
 

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`).