# Amazon SQS Transport

<!-- Version variant: sqs_8; default: [/transports/sqs/index.md](/transports/sqs/index.md) -->


[Simple Queue Service (SQS)](https://aws.amazon.com/sqs/) is a message queue service provided by [Amazon Web Services](https://aws.amazon.com/).

## Transport at a glance

|Feature                    |   |
|:---                       |---
|Transactions |None, ReceiveOnly (Message visibility timeout)
|Pub/Sub                    |Native (Requires SNS, supports hybrid-mode for migration purposes)
|Timeouts                   |Native (Requires FIFO Queues)
|Large message bodies       |Native (Requires S3)
|Scale-out             |Competing consumer
|Scripted Deployment        |Built-in CLI, C#
|Installers                 |Optional
|Native integration         |[Supported](native-integration.md)
|FIFO input queues          |Not supported
|Case Sensitive             |Yes
|Local development          |[Supported via LocalStack](/nservicebus/aws/local-development.md)
|Aspire integration         |[Yes](/platform/aspire/index.md#configuring-the-transport-amazon-sqs)

The FIFO queue used for unrestricted delayed delivery does not provide FIFO semantics for an endpoint's input queue. Support for FIFO endpoint queues is being considered. If ordered message-group processing is required, [add a thumbs-up or share the use case on issue #240](https://github.com/Particular/NServiceBus.AmazonSQS/issues/240).

## Advantages

* Fully managed turn-key messaging infrastructure. SQS queues requires little effort to set up, maintain, and manage over time.
* Integrates seamlessly with other services provided by AWS, such as [IAM](https://docs.aws.amazon.com/iam/index.html), [CloudWatch](https://aws.amazon.com/cloudwatch/), and [Lambda](https://aws.amazon.com/lambda/). For organizations already committed to AWS, SQS is a natural choice.
* Can be used as a gateway between endpoints that may not have direct connectivity to each other.
* Can send and receive large messages that exceed the queue limitations by storing large payloads in S3. For more information review the documentation for the transport [topology](topology.md#s3) and [configuration options](configuration-options.md).

## Disadvantages

* Like other message brokers, there is no local store-and-forward mechanism available. If an endpoint cannot reach SQS, either due to network problems or if SQS is unavailable, the endpoint will not be able to send nor receive messages.
* Can be expensive with large volumes of messages.

## Prerequisites

An [AWS IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) account with a pair of [Access Keys](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-getting-started.html) is required.

The IAM account requires the following permissions to provision infrastructure and run the transport:

#### [SQS permissions](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-api-permissions-reference.html)

* CreateQueue
* DeleteMessage
* DeleteMessageBatch
* GetQueueUrl
* ReceiveMessage
* SendMessage
* SendMessageBatch
* SetQueueAttributes
* GetQueueAttributes
* ChangeMessageVisibility
* ChangeMessageVisibilityBatch
* PurgeQueue

#### [SNS permissions](https://docs.aws.amazon.com/sns/latest/dg/sns-access-policy-language-api-permissions-reference.html)

 * CreateTopic
 * ListTopics
 * GetTopicAttributes
 * SetTopicAttributes
 * SetEndpointAttributes
 * Publish
 * Subscribe
 * Unsubscribe
 * ListSubscriptions
 * ListSubscriptionsByTopic
 * GetSubscriptionAttributes
 * SetSubscriptionAttributes

In addition to the above permissions the queue subscribing to a topic needs `sqs:SendMessage` permission to enable the topics delivering messages to the subscribing queue.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SomeSid",
      "Effect": "Allow",
      "Principal": {
        "AWS": "yourPrincipal"
      },
      "Action": "sqs:SendMessage",
      "Resource": "arn:aws:sqs:yourQueueArn",
      "Condition": {
        "ArnLike": {
          "aws:SourceArn": "arn:aws:sns:yourTopicArn"
        }
      }
    },
  ]
}
```


#### [S3 permissions](https://docs.aws.amazon.com/AmazonS3/latest/dev/using-with-s3-actions.html)

* CreateBucket
* DeleteObject
* GetObject
* PutObject
* PutLifecycleConfiguration
* GetLifecycleConfiguration
* ListAllMyBuckets

#### Other permissions

* If using server-side encryption of SQS queues, all NServiceBus endpoints (as well as [ServiceControl](/servicecontrol/index.md)) will require the `kms:GenerateDataKey` permission in order to support [key management](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-key-management.html).

## Configuration

By default, [AWS Access Key ID, AWS Secret Access Key](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) and [AWS Region Key](https://docs.aws.amazon.com/general/latest/gr/rande.html#sqs_region) are discovered from environment variables of the machine that is running the endpoint:

 * Access Key ID goes in `AWS_ACCESS_KEY_ID`
 * Secret Access Key goes in `AWS_SECRET_ACCESS_KEY`
 * Region Key goes in `AWS_REGION`

<!-- snippet: SqsTransport -->

```cs
// S3 bucket only required for messages larger than
// 256KB (version 8.0) or commands larger than 1MB 
// and events larger than 256KB(version 8.1 and later)
var transport = new SqsTransport
{
    S3 = new S3Settings("myBucketName", "my/key/prefix")
};

endpointConfiguration.UseTransport(transport);
```

<!-- endsnippet -->

For more configuration options consult the [configuration options](/transports/sqs/configuration-options.md) page.

> [!NOTE]
> The existing API surface with `UseTransport<T>()` is supported via a [shim API](https://en.wikipedia.org/wiki/Shim_(computing)) to ease migration. However, it is recommended to switch to the new transport configuration API to prepare for future upgrades of NServiceBus.


## Retries and timeouts

The SQS transport uses the default [retry and timeout](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/retries-timeouts.html) values implemented by the [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/):

| Parameter          | Default value |
|--------------------|---------------|
| `MaxErrorRetries`  | 4             |
| `RequestTimeout`   | 100s          |
| `ReadWriteTimeout` | 300s          |

> [!NOTE]
> NServiceBus will perform [immediate](/nservicebus/recoverability/index.md#immediate-retries) and [delayed](/nservicebus/recoverability/index.md#delayed-retries) retries in addition to retries performed internally by the SQS client.

## Batching

Messages sent from within a handler are [batched](/nservicebus/messaging/batched-dispatch.md) with up to ten messages per batch depending on the size of the message. Messages sent outside a handler are not batched.