# Create a queue

Create a standard or FIFO queue, with or without a dead-letter queue, and choose its delivery settings.

Replace _my-queue_ with the name of your queue. A name is 1 to 80 letters, digits, hyphens or
underscores, unique in your organization and region; a FIFO queue's name ends in `.fifo` (counted
in the 80). The name and the type cannot be changed later.

## Prerequisites

- Permission for `queue:CreateQueue` on every queue you create. The console's dead-letter option
  creates two queues. Without it, the console shows **Create queue** as unavailable.
- For the console, also `queue:ListQueues` to open **Queues**, and `queue:GetQueueAttributes` to
  open the new queue's page.
- Room in the **Queues** quota, which counts dead-letter queues too (see [Quotas](quotas.md)).
- To name a dead-letter queue, that queue must already exist.

## Defaults differ between the console and the other interfaces

| Setting           | Console                                                      | API, CLI, Terraform |
| ----------------- | ------------------------------------------------------------ | ------------------- |
| Dead-letter queue | On: creates `<name>-dlq` with 14 days' retention, 5 receives | None                |
| Everything else   | The defaults below                                           | The defaults below  |

| Setting                     | Default for a new queue | Range                                          |
| --------------------------- | ----------------------- | ---------------------------------------------- |
| Visibility timeout          | 30 s                    | 0 s to 12 hours (`visibilityTimeoutSeconds`)   |
| Retention                   | 4 days                  | 60 s to 14 days (`retentionSeconds`)           |
| Delivery delay              | 0 s                     | 0 to 900 s (`delaySeconds`)                    |
| Receive wait                | 0 s                     | 0 to 20 s (`receiveWaitSeconds`)               |
| Maximum message size        | 256 KiB                 | 1,024 to 262,144 bytes (`maximumMessageBytes`) |
| Content-based deduplication | Off                     | FIFO queues only (`contentBasedDeduplication`) |

## Create the queue

You pay for requests and stored messages once you use the queue.

**Console**
1. Open **Queues**, then choose **Create queue**.
2. For **Name**, enter my-queue.
3. (Optional) Select **FIFO queue**. The console adds `.fifo` to the name. To deduplicate sends by
   their body, also select **Content-based deduplication**.
4. Leave **Dead-letter queue** selected to also create `my-queue-dlq` (`my-queue-dlq.fifo` for a
   FIFO queue), and enter in the box beside it after how many receives a message moves there
   (1 to 1000). Or clear **Dead-letter queue**.
5. Choose **Create**.

The console creates the dead-letter queue first, then the queue, and opens the queue's page. The
other settings take the defaults; change them under **Settings** (see
[Change a queue's settings](change-queue-settings.md)). The dialog does not let you create a queue
whose name, or whose `-dlq` name, is already taken. If creating the queue fails after its
dead-letter queue was created, the dead-letter queue stays.

**CLI**
```sh
dcloud queue queues create --name my-queue --visibility-timeout-seconds 60
```

With a dead-letter queue, create that first:

```sh
dcloud queue queues create --name my-queue-dlq
dcloud queue queues create --name my-queue --dead-letter-queue '{"name":"my-queue-dlq","maxReceiveCount":5}'
```

A FIFO queue:

```sh
dcloud queue queues create --name orders.fifo --fifo --content-based-deduplication
```

**API**
```http
POST /queue/api/queues
{ "name": "my-queue", "visibilityTimeoutSeconds": 60, "deadLetterQueue": { "name": "my-queue-dlq", "maxReceiveCount": 5 } }
```

A FIFO queue needs `"fifo": true` and a name ending in `.fifo`:

```http
POST /queue/api/queues
{ "name": "orders.fifo", "fifo": true, "contentBasedDeduplication": true }
```

The answer is `201` with the queue, its settings and its message counts (all 0).

**Terraform**
```hcl
resource "dcloud_queue" "dlq" {
  name = "my-queue-dlq"
}

resource "dcloud_queue" "main" {
  name                       = "my-queue"
  visibility_timeout_seconds = 60
  dead_letter_queue = jsonencode({
    name            = dcloud_queue.dlq.name
    maxReceiveCount = 5
  })
}
```

For a FIFO queue, set `fifo = true` and a name ending in `.fifo`. Changing `name` or `fifo` replaces
the queue, and deleting a queue deletes its messages.

## Result

The queue exists with the settings you chose and is ready to receive sends.

## When creation is refused

- `409` "A queue named “my-queue” already exists." (code `QueueAlreadyExists`).
- `409` with code `QuotaExceeded` when the Queues quota is used up: "Quota exceeded: Queues
  (queue.queues) — …".
- `400` "The name of a FIFO queue must end with .fifo." or "A queue named .fifo must be created as a
  FIFO queue."
- `400` "ContentBasedDeduplication applies only to FIFO queues."
- `404` "There is no queue named “my-queue-dlq” to use as the dead-letter queue." when the
  dead-letter queue does not exist yet, and `400` when its type differs: "The dead-letter queue of
  a FIFO queue must also be a FIFO queue." or "The dead-letter queue of a standard queue must also
  be a standard queue."
- `400` "A queue cannot be its own dead-letter queue." when the queue names itself.

## Related

- [Change a queue's settings](change-queue-settings.md)
- [Dead-letter queues](dead-letter-queues.md)
- [FIFO queues](fifo-queues.md)
