Nov 19, 20267 min read

How to Use Amazon SQS from Go

Send, receive and delete SQS messages with the AWS SDK for Go v2, with long polling, visibility timeouts, batch deletes, dead-letter queues and a graceful consumer loop.

Illustration for How to Use Amazon SQS from Go

Amazon SQS is the queue most Go services on AWS start with, and sending a message with the AWS SDK for Go v2 takes a few lines. The consumer takes more care, with long polling, visibility timeouts, batch deletes and a loop that stops cleanly on SIGTERM.

This guide writes both sides with the SDK, then shows the same producer and consumer as typed Pub/Sub on SNS and SQS that is provisioned for you.

SQS from Go at a glance

Encore Pub/SubAWS SDK for Go v2
Queue setupDeclared in Go, created on deployConsole, CLI, Terraform or CloudFormation
Message typeGo struct, typed on both endsString body you marshal yourself
Receive loopRuns for youReceiveMessage in your own goroutine
Delete on successAutomatic when the handler returns nilDeleteMessage or DeleteMessageBatch
Retries and DLQRetryPolicy with backoff, DLQ per subscriptionRedrive policy you configure
Fan-outMany subscriptions on one topicSNS topic plus a queue per consumer
Local developmentIn-process broker under encore runA real queue, or an emulator
IAMEncore provisions an IAM role for the serviceRole and policy you write

How do you use SQS with Encore?

Encore

Encore is a backend framework with built-in infrastructure, and its Pub/Sub API covers the producer and consumer in a few declarations. On AWS each topic becomes an SNS topic and each subscription its own SQS queue with a dead-letter queue, so the loop, the deletes and the redrive are not code you maintain.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create shop --example=hello-world$ cd shop && mkdir orders email

The orders service declares the topic and publishes from an endpoint:

// orders/orders.go package orders import ( "context" "encore.dev/pubsub" ) type OrderPlaced struct { OrderID string `json:"order_id"` Email string `json:"email"` } // SNS with an SQS queue per subscription on AWS, Pub/Sub on GCP, // an in-process broker under encore run. var OrderPlacedTopic = pubsub.NewTopic[*OrderPlaced]("order-placed", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, }) type PlaceParams struct { OrderID string `json:"order_id"` Email string `json:"email"` } type PlaceResponse struct { MessageID string `json:"message_id"` } //encore:api public method=POST path=/orders func Place(ctx context.Context, p *PlaceParams) (*PlaceResponse, error) { id, err := OrderPlacedTopic.Publish(ctx, &OrderPlaced{OrderID: p.OrderID, Email: p.Email}) if err != nil { return nil, err } return &PlaceResponse{MessageID: id}, nil }

The email service subscribes, with AckDeadline in the role of the visibility timeout, MaxConcurrency caps parallel handlers, and after MaxRetries failed attempts the message moves to the subscription's dead-letter queue. The handler skips orders it already confirmed, because delivery is at least once:

// email/email.go package email import ( "context" "sync" "time" "encore.app/orders" "encore.dev/pubsub" "encore.dev/rlog" ) // sent stands in for a table with a unique order_id column. var ( mu sync.Mutex sent = map[string]bool{} ) var _ = pubsub.NewSubscription(orders.OrderPlacedTopic, "send-confirmation", pubsub.SubscriptionConfig[*orders.OrderPlaced]{ Handler: sendConfirmation, AckDeadline: 60 * time.Second, MaxConcurrency: 20, RetryPolicy: &pubsub.RetryPolicy{ MinBackoff: 10 * time.Second, MaxBackoff: 5 * time.Minute, MaxRetries: 5, // then the dead-letter queue }, }, ) func sendConfirmation(ctx context.Context, evt *orders.OrderPlaced) error { mu.Lock() defer mu.Unlock() if sent[evt.OrderID] { return nil // duplicate delivery } rlog.Info("sending confirmation", "order_id", evt.OrderID, "email", evt.Email) sent[evt.OrderID] = true return nil // returning an error retries with backoff }

Under encore run, posting the same order twice logs one confirmation, and the trace for the request shows the publish and the handler as one timeline:

~/shop
$ encore run$ curl -X POST localhost:4000/orders -d '{"order_id":"ord_1","email":"ada@example.com"}'{"message_id": "dbvb16e8qngdjlgnnhs0"}INF sending confirmation email=ada@example.com order_id=ord_1 service=email

Tests check publishing without running subscribers: et.Topic(OrderPlacedTopic).PublishedMessages() returns what a test published, isolated per test. On deploy to your own AWS account, Encore creates the topic, queues and dead-letter queues, and provisions an IAM role for the service with publish and consume permissions on them.

The topic and its subscribers are declarations in the code, so a coding agent can add a second consumer in the same change as the handler, run it under encore run and watch both receive the event before anything touches AWS.

Best fit: Go services that want SQS-backed messaging with typed events, retries and a dead-letter queue per consumer in their own AWS account.

How do you use SQS with the AWS SDK for Go v2?

AWS SDK for Go v2

The SDK client loads credentials from the default chain: environment variables, the shared config file, SSO, or the role of the ECS task, Lambda function or EC2 instance. These examples use github.com/aws/aws-sdk-go-v2/service/sqs v1.53.

Sending messages

SendMessage takes a string body, so the event is marshaled to JSON first. Message attributes carry metadata a consumer can read without parsing the body:

type OrderPlaced struct { OrderID string `json:"order_id"` Email string `json:"email"` } func sendOrder(ctx context.Context, client *sqs.Client, queueURL string, evt OrderPlaced) error { body, err := json.Marshal(evt) if err != nil { return err } _, err = client.SendMessage(ctx, &sqs.SendMessageInput{ QueueUrl: aws.String(queueURL), MessageBody: aws.String(string(body)), MessageAttributes: map[string]types.MessageAttributeValue{ "type": {DataType: aws.String("String"), StringValue: aws.String("order.placed")}, }, }) return err }

Receiving and deleting messages

The consumer is a loop around ReceiveMessage. WaitTimeSeconds: 20 turns on long polling, which waits for messages instead of returning empty responses you pay for. A message only leaves the queue when you delete it, so the loop collects successful receipt handles and deletes them in one batch:

func consume(ctx context.Context, client *sqs.Client, queueURL string, handle func(context.Context, OrderPlaced) error) error { for { out, err := client.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{ QueueUrl: aws.String(queueURL), MaxNumberOfMessages: 10, WaitTimeSeconds: 20, // long polling VisibilityTimeout: 60, // seconds to finish before redelivery MessageAttributeNames: []string{"All"}, }) if errors.Is(ctx.Err(), context.Canceled) { return nil // shutting down } if err != nil { return err } var done []types.DeleteMessageBatchRequestEntry for _, m := range out.Messages { var evt OrderPlaced if err := json.Unmarshal([]byte(aws.ToString(m.Body)), &evt); err != nil { log.Printf("bad message %s: %v", aws.ToString(m.MessageId), err) continue // the redrive policy moves it to the DLQ } if err := handle(ctx, evt); err != nil { log.Printf("order %s failed: %v", evt.OrderID, err) continue // visible again after the timeout } done = append(done, types.DeleteMessageBatchRequestEntry{ Id: m.MessageId, ReceiptHandle: m.ReceiptHandle, }) } if len(done) > 0 { res, err := client.DeleteMessageBatch(ctx, &sqs.DeleteMessageBatchInput{ QueueUrl: aws.String(queueURL), Entries: done, }) if err != nil { return err } for _, f := range res.Failed { log.Printf("delete failed for %s: %s", aws.ToString(f.Id), aws.ToString(f.Message)) } } } }

DeleteMessageBatch can partly fail while returning no error, which is why the loop checks res.Failed; an entry that fails to delete is redelivered later, and the handler has to tolerate that. main wires the client to a context that is cancelled on SIGTERM, so ECS or Kubernetes can stop the consumer between polls:

func main() { ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() cfg, err := config.LoadDefaultConfig(ctx) if err != nil { log.Fatal(err) } client := sqs.NewFromConfig(cfg) err = consume(ctx, client, os.Getenv("ORDERS_QUEUE_URL"), func(ctx context.Context, evt OrderPlaced) error { log.Printf("sending confirmation for %s to %s", evt.OrderID, evt.Email) return nil }) if err != nil { log.Fatal(err) } }

Queues, dead-letter queues and IAM

The queue itself comes from outside the code, and a redrive policy with maxReceiveCount moves a message to a dead-letter queue after that many receives, and the visibility timeout should exceed the slowest handler, or a message is processed twice while the first attempt is still running. The consumer's role needs sqs:ReceiveMessage and sqs:DeleteMessage on the queue, plus sqs:ChangeMessageVisibility if it extends timeouts, and the producer's needs sqs:SendMessage.

For more than one consumer of the same event, the usual shape is an SNS topic with one SQS queue subscribed per consumer, which is more resources and more policies for each new subscriber.

Best fit: Go services that already have their queues defined in Terraform or CloudFormation and need full control over receive, batching and visibility.

How to choose

Use the SDK directly when the queues already exist, when you need SQS features such as FIFO message groups or per-message visibility changes, or when the consumer is part of a larger system you do not control. Use Encore when the queue exists to connect your own services, since topics, subscriptions, dead-letter queues and IAM come from the same Go declarations that run locally under encore run.

Frequently asked questions

How do I receive messages from SQS in Go?

Create a client with sqs.NewFromConfig and call ReceiveMessage in a loop with MaxNumberOfMessages up to 10 and WaitTimeSeconds 20 for long polling. Process each message, then delete it with DeleteMessage or DeleteMessageBatch using its receipt handle; anything not deleted becomes visible again after the visibility timeout.

Why are my SQS messages delivered more than once?

Standard queues deliver at least once, and a message also reappears when your consumer does not delete it before the visibility timeout ends. Make the handler idempotent, for example by recording processed IDs under a unique key, and set the visibility timeout longer than the slowest handler.

What IAM permissions does a Go SQS consumer need?

sqs:ReceiveMessage and sqs:DeleteMessage on the queue, plus sqs:ChangeMessageVisibility if it extends the timeout and sqs:GetQueueAttributes if it reads attributes. A producer needs sqs:SendMessage. Grant them to the role the task or function runs as rather than to access keys.

How do I use SQS from Go with Encore?

Declare a topic with pubsub.NewTopic and a subscription with pubsub.NewSubscription and a handler function. On AWS, Encore provisions an SNS topic with an SQS queue and a dead-letter queue per subscription, runs the receive and delete loop for you, and retries a message when the handler returns an error.

Deploy to your cloud on AWS and Google Cloud
without managing infrastructure

Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders