diff --git a/src/assets/images/queues/customize-retention-period.png b/src/assets/images/queues/customize-retention-period.png new file mode 100644 index 00000000000000..d6276dd39f4b4f Binary files /dev/null and b/src/assets/images/queues/customize-retention-period.png differ diff --git a/src/content/changelog/queues/2025-02-14-customize-queue-retention-period.mdx b/src/content/changelog/queues/2025-02-14-customize-queue-retention-period.mdx new file mode 100644 index 00000000000000..88c05ed7c7743f --- /dev/null +++ b/src/content/changelog/queues/2025-02-14-customize-queue-retention-period.mdx @@ -0,0 +1,19 @@ +--- +title: Customize queue message retention periods +description: Customize the retention period for a queue, from a minimum of 60 seconds to a maximum of 14 days. +products: + - queues +date: 2025-02-14 12:00:00 UTC +--- + +You can now customize a queue's message retention period, from a minimum of 60 seconds to a maximum of 14 days. Previously, it was fixed to the default of 4 days. + +![Customize a queue's message retention period](~/assets/images/queues/customize-retention-period.png) + +You can customize the retention period on the settings page for your queue, or using Wrangler: + +```bash title="Update message retention period" +$ wrangler queues update my-queue --message-retention-period-secs 600 +``` + +This feature is available on all new and existing queues. If you haven't used Cloudflare Queues before, [get started with the Cloudflare Queues guide](/queues/get-started). diff --git a/src/content/docs/queues/configuration/configure-queues.mdx b/src/content/docs/queues/configuration/configure-queues.mdx index 9c6080c09364d8..f1586511b4b931 100644 --- a/src/content/docs/queues/configuration/configure-queues.mdx +++ b/src/content/docs/queues/configuration/configure-queues.mdx @@ -9,23 +9,41 @@ head: --- -import { WranglerConfig } from "~/components"; +import { WranglerConfig, Type } from "~/components"; Cloudflare Queues can be configured using [Wrangler](/workers/wrangler/install-and-update/), the command-line interface for Cloudflare's Developer Platform, which includes [Workers](/workers/), [R2](/r2/), and other developer products. -Each Worker has a [Wrangler configuration file](/workers/wrangler/configuration/) that specifies environment variables, triggers, and resources, such as a Queue. To enable Worker-to-resource communication, you must set up a [binding](/workers/runtime-apis/bindings/) in your Worker project's Wrangler file. + +Each Producer and Consumer Worker has a [Wrangler configuration file](/workers/wrangler/configuration/) that specifies environment variables, triggers, and resources, such as a queue. To enable Worker-to-resource communication, you must set up a [binding](/workers/runtime-apis/bindings/) in your Worker project's Wrangler file. Use the options below to configure your queue. :::note -Below are options for Queues, refer to the Wrangler documentation for a full reference of the [Wrangler configuration file](/workers/wrangler/configuration/). +Below are options for queues, refer to the Wrangler documentation for a full reference of the [Wrangler configuration file](/workers/wrangler/configuration/). ::: -## Producer +## Queue configuration +The following queue level settings can be configured using Wrangler: + +```sh +$ npx run wrangler queues update --delivery-delay-secs 60 --message-retention-period-secs 3000 +``` + +* `--delivery-delay-secs` + * How long a published message is delayed for, before it is delivered to consumers. + * Must be between 0 and 43200 (12 hours). + * Defaults to 0. + +* `--message-retention-period-secs` + * How long messages are retained on the Queue. + * Defaults to 345600 (4 days). + * Must be between 60 and 1209600 (14 days) + +## Producer Worker configuration A producer is a [Cloudflare Worker](/workers/) that writes to one or more queues. A producer can accept messages over HTTP, asynchronously write messages when handling requests, and/or write to a queue from within a [Durable Object](/durable-objects/). Any Worker can write to a queue. @@ -43,19 +61,17 @@ To produce to a queue, set up a binding in your Wrangler file. These options sho -* queue string +* queue - * The name of the Queue. + * The name of the queue. -* binding string +* binding * The name of the binding, which is a JavaScript variable. -## Consumer - -## Workers +## Consumer Worker Configuration To consume messages from one or more queues, set up a binding in your Wrangler file. These options should be used when a Worker wants to receive messages from a queue. @@ -78,32 +94,32 @@ Refer to [Limits](/queues/platform/limits) to review the maximum values for each -* queue string +* queue - * The name of the Queue. + * The name of the queue. -* max\_batch\_size number optional +* max\_batch\_size * The maximum number of messages allowed in each batch. * Defaults to `10` messages. -* max\_batch\_timeout number optional +* max\_batch\_timeout * The maximum number of seconds to wait until a batch is full. * Defaults to `5` seconds. -* max\_retries number optional +* max\_retries * The maximum number of retries for a message, if it fails or [`retryAll()`](/queues/configuration/javascript-apis/#messagebatch) is invoked. * Defaults to `3` retries. -* dead\_letter\_queue string optional +* dead\_letter\_queue - * The name of another Queue to send a message if it fails processing at least `max_retries` times. + * The name of another queue to send a message if it fails processing at least `max_retries` times. * If a `dead_letter_queue` is not defined, messages that repeatedly fail processing will eventually be discarded. - * If there is no Queue with the specified name, it will be created automatically. + * If there is no queue with the specified name, it will be created automatically. -* max\_concurrency number optional +* max\_concurrency * The maximum number of concurrent consumers allowed to run at once. Leaving this unset will mean that the number of invocations will scale to the [currently supported maximum](/queues/platform/limits/). * Refer to [Consumer concurrency](/queues/configuration/consumer-concurrency/) for more information on how consumers autoscale, particularly when messages are retried. diff --git a/src/content/docs/workers/wrangler/commands.mdx b/src/content/docs/workers/wrangler/commands.mdx index 9eb040eee4568e..e0ab485c8cbc1d 100644 --- a/src/content/docs/workers/wrangler/commands.mdx +++ b/src/content/docs/workers/wrangler/commands.mdx @@ -1244,7 +1244,7 @@ Manage your Workers [Queues](/queues/) configurations. ### `create` -Create a new Queue. +Create a new queue. ```txt wrangler queues create [OPTIONS] @@ -1254,6 +1254,25 @@ wrangler queues create [OPTIONS] - The name of the queue to create. - `--delivery-delay-secs` - How long a published message should be delayed for, in seconds. Must be a positive integer. +- `--message-retention-period-secs` + - How long a published message is retained in the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days). + + + +### `update` + +Update an existing queue. + +```txt +wrangler queues update [OPTIONS] +``` + +- `name` + - The name of the queue to update. +- `--delivery-delay-secs` + - How long a published message should be delayed for, in seconds. Must be a positive integer. +- `--message-retention-period-secs` + - How long a published message is retained on the Queue. Must be a positive integer between 60 and 1209600 (14 days). Defaults to 345600 (4 days).