An SQS queue lets you send, store, and receive messages between software components at any volume without losing messages or requiring other services to be available. It's a reliable way to decouple and connect microservices.
Under the hood, Stacktape uses Amazon Simple Queue Service (SQS).
When to use them
Stacktape offers three managed resources for messaging and communication:
- SNS topics
- SQS queues
- Event buses
Use an SNS topic when:
- You need to publish messages to many different subscribers with a single action.
- You require high throughput and reliability.
Use an SQS queue when:
- You need reliable, one-to-one, asynchronous communication to decouple your applications.
- You want to control the rate at which messages are consumed.
Use an event bus when:
- You want to publish messages to many subscribers and use the event data itself to filter which messages are delivered to which subscribers.
- You need to integrate with third-party SaaS providers like Shopify, Datadog, or PagerDuty.
Basic usage
You don't need to specify any properties to create a basic SQS queue.
SqsQueueAPI referencetypeRequired
Type: string "sqs-queue"
properties.delayMessagesSecond
Delay (in seconds) before new messages become visible to consumers. Range: 0–900.
Type: number
Useful for introducing a buffer, e.g., waiting for related data to be available before processing.
properties.maxMessageSizeBytesDefault: 262144
Maximum message size in bytes. Range: 1,024 (1 KB) to 262,144 (256 KB).
Type: number
Messages larger than this limit are rejected. For payloads over 256 KB, store the data in S3 and send the reference.
properties.messageRetentionPeriodSecondsDefault: 345600
How long unprocessed messages stay in the queue before being deleted. Range: 60s to 1,209,600s (14 days).
Type: number
Default is 4 days (345,600s). Increase if consumers might fall behind or be temporarily offline.
properties.longPollingSeconds
Seconds the queue waits for messages before returning an empty response. Range: 0–20.
Type: number
Set to 1–20 to enable long polling, which reduces costs by making fewer API calls.
With short polling (0), the consumer gets an immediate (often empty) response and must poll again.
Recommended: 20 for most workloads — it's the most cost-effective.
properties.visibilityTimeoutSecondsDefault: 30
How long (seconds) a message is hidden from other consumers after being received. Range: 0–43,200 (12 hours).
Type: number
After a consumer picks up a message, it must delete it before this timeout expires — otherwise it becomes visible again and can be processed by another consumer (duplicate processing).
Set this higher than your expected processing time. If your tasks take 2 minutes, use at least 150 seconds.
properties.fifoEnabled
Creates a FIFO queue that guarantees message order and exactly-once delivery.
Type: boolean
Use when processing order matters (e.g., financial transactions, sequential workflows). FIFO queues have lower throughput (~300 msg/s without batching, ~3,000 with) compared to standard queues.
Requires either contentBasedDeduplication: true or a MessageDeduplicationId on each message.
properties.fifoHighThroughput
Enables high-throughput mode for FIFO queues (up to ~70,000 msg/s per queue).
Type: boolean
Messages are partitioned by MessageGroupId — order is guaranteed within each group but not across groups.
Requires fifoEnabled: true.
properties.contentBasedDeduplication
Automatically deduplicates messages based on their content (SHA-256 hash of the body).
Type: boolean
Within the 5-minute deduplication window, identical messages are delivered only once.
Saves you from having to generate a unique MessageDeduplicationId for each message.
Requires fifoEnabled: true.
properties.redrivePolicy
Moves messages that fail processing too many times to a dead-letter queue for inspection.
Type: SqsQueueRedrivePolicy
After maxReceiveCount failed attempts, the message is automatically moved to a separate queue
so you can investigate and reprocess it. Prevents poison messages from blocking the queue.
properties.alarms
Additional alarms associated with this resource.
Type: Array of SqsQueueAlarm
These alarms will be merged with any alarms configured globally in the console.
properties.disabledGlobalAlarms
Disables globally configured alarms for this resource.
Type: Array of string
Provide a list of alarm names as configured in the console.
properties.policyStatements
Custom access-control statements added to the queue's resource policy.
Type: Array of SqsQueuePolicyStatement
These are merged with policies Stacktape auto-generates. Use to grant cross-account access or allow specific AWS services (e.g., SNS) to send messages to this queue.
properties.events
A list of event sources that trigger message delivery to this queue.
Type: Array of SqsQueueEventBusIntegration
Currently supports EventBridge event bus integration for delivering events directly to the queue.
overrides
Escape hatch to modify the underlying CloudFormation resources Stacktape creates.
Type: Object
Use dot-notation paths to override specific properties on any child resource.
Find resource logical IDs with stacktape stack-info --detailed.
overrides:
MyDbInstance:
Properties.StorageEncrypted: true
Integrating with workloads
You can trigger a function or a batch job whenever messages are available in an SQS queue. Messages are processed in batches. If the function or batch job fails, the messages will reappear in the queue after the visibility timeout.
A Lambda function with an SQS queue integration.
You can also receive messages using the AWS SDK, as shown in this worker service example:
The code for
processing.ts.
Sending messages
You can use the AWS SDK to send messages to a queue.
FIFO
You can enable FIFO (First-In, First-Out) to ensure that messages are processed in the exact order that they are sent.
Use when processing order matters (e.g., financial transactions, sequential workflows). FIFO queues have lower throughput (~300 msg/s without batching, ~3,000 with) compared to standard queues.
Requires either contentBasedDeduplication: true or a MessageDeduplicationId on each message.
Content-based deduplication
You can enable content-based deduplication to prevent duplicate messages from being sent.
Within the 5-minute deduplication window, identical messages are delivered only once.
Saves you from having to generate a unique MessageDeduplicationId for each message.
Requires fifoEnabled: true.
Visibility timeout
The visibility timeout is the amount of time that a message is hidden from other consumers after it has been received. This prevents other consumers from processing the same message.
After a consumer picks up a message, it must delete it before this timeout expires — otherwise it becomes visible again and can be processed by another consumer (duplicate processing).
Set this higher than your expected processing time. If your tasks take 2 minutes, use at least 150 seconds.
You can set the visibility timeout using the visibilityTimeoutSeconds property.