SQS Queues



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:

  1. SNS topics
  2. SQS queues
  3. 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.

resources:
  mainQueue:
    type: sqs-queue
SqsQueueAPI reference
typeRequired
No description

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.

resources:
  myLambda:
    type: function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: path/to/my-lambda.ts
      events:
        - type: sqs
          properties:
            sqsQueueName: mySqsQueue

  mySqsQueue:
    type: sqs-queue

A Lambda function with an SQS queue integration.

You can also receive messages using the AWS SDK, as shown in this worker service example:

resources:
  myQueue:
    type: sqs-queue
    properties:
      fifoEnabled: true

  processing:
    type: worker-service
    properties:
      packaging:
        type: stacktape-image-buildpack
        properties:
          entryfilePath: processing.ts
      connectTo:
        - myQueue
      resources:
        cpu: 0.25
        memory: 512
import { DeleteMessageCommand, ReceiveMessageCommand, SQSClient } from '@aws-sdk/client-sqs';

const sqsClient = new SQSClient({});

const interval = setInterval(async () => {
  try {
    const { Messages } = await sqsClient.send(new ReceiveMessageCommand({ QueueUrl: process.env.STP_MY_QUEUE_URL }));
    if (Messages?.length) {
      // do some message processing
      // .....

      // After processing, delete messages from queue.
      // If you do NOT delete messages, they will become visible after visibility timeout elapses.
      // This can lead to same message being processed twice.
      await Promise.all(
        Messages.map(({ ReceiptHandle }) =>
          sqsClient.send(new DeleteMessageCommand({ QueueUrl: process.env.STP_MY_QUEUE_URL, ReceiptHandle }))
        )
      );
    }
    console.info('Nothing to process');
  } catch (err) {
    // error handling
    console.error(err);
    clearInterval(interval);
  }
}, 10000);

The code for processing.ts.

Sending messages

You can use the AWS SDK to send messages to a queue.

import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";

const sqsClient = new SQSClient({});

sqsClient.send(
  new SendMessageCommand({
    MessageBody: "Hello from the other side",
    QueueUrl: process.env.STP_MY_QUEUE_URL,
  })
);

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.

resources:
  mainQueue:
    type: sqs-queue
    properties:
      fifoEnabled: true

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.

resources:
  mainQueue:
    type: sqs-queue
    properties:
      visibilityTimeoutSeconds: 300