docs: improve queueName docs to avoid high cardinality

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

@@ -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)

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