Nov 16, 20267 min read

Pub/Sub Ordering Keys on Google Cloud: How Message Ordering Works

How ordering keys work in Google Cloud Pub/Sub, what you need on the publisher and the subscription, the 1 MBps per key limit, how redelivery and dead-letter topics affect order, and how Encore sets ordering from a topic attribute.

Illustration for Pub/Sub Ordering Keys on Google Cloud: How Message Ordering Works

Most Pub/Sub consumers do not care about order, and Pub/Sub does not provide it by default. Some do: a shipment that goes from picked_up to in_transit must not end up picked_up because two events were delivered the other way round. Ordering keys give you per-key order without giving up Pub/Sub's scaling, provided the publisher, the subscription and the handler each do their part.

This guide covers how ordering keys work in Google Cloud Pub/Sub, what to enable where, the throughput limits, how redelivery and dead-letter topics affect order, and how Encore sets ordering from a topic attribute in Go.

Pub/Sub ordering keys at a glance

Requirement or limit
MessageSame ordering key on related messages, up to 1 KB
PublisherOrdering enabled on the client, all messages for a key published in one region
SubscriptionMessage ordering enabled, chosen at creation
Throughput1 MBps per ordering key
ScopeOrder within a key only, nothing across keys
RedeliveryRedelivering one message redelivers the later ones for its key
Dead-letter topicOrder is not guaranteed for messages written to it
EncoreOrderingAttribute on the topic, no effect locally

From Google Cloud's message ordering guide.

How ordering keys work

An ordering key is a string on each message that groups related messages, such as a customer ID, an order ID or a row's primary key. Pub/Sub delivers messages with the same key in the order the service received them from the publisher, to every subscription created with message ordering enabled. Subscriptions on the same topic without ordering get the same messages in no particular order, and messages with an empty key are never ordered.

Keys are not partitions: Pub/Sub expects many keys, up to billions, and more keys means more parallel delivery, since only messages sharing a key wait for each other. Pick the narrowest key that captures the order you need: per shipment rather than per warehouse, per account rather than per region. The limit that follows from that choice is 1 MBps of publishing per key.

Order is defined at publish time, which puts two rules on the publisher. All messages for a key must go through the same region, which in practice means a regional endpoint rather than the global one when publishers run in several regions. And the client has to publish them in order: with ordering enabled, the client library keeps the messages for each key in sequence, and if a publish fails it pauses that key so later messages do not jump ahead, until the code calls ResumePublish.

Publishing with ordering keys in Go

// publisher/main.go package main import ( "context" "fmt" "log" "os" "cloud.google.com/go/pubsub/v2" "google.golang.org/api/option" ) func main() { ctx := context.Background() // Ordering holds per region: publish every message for a key to the same one. client, err := pubsub.NewClient(ctx, os.Getenv("PROJECT_ID"), option.WithEndpoint("europe-west1-pubsub.googleapis.com:443")) if err != nil { log.Fatal(err) } defer client.Close() pub := client.Publisher("shipment-status") pub.EnableMessageOrdering = true defer pub.Stop() for seq, status := range []string{"label_created", "picked_up", "in_transit", "delivered"} { res := pub.Publish(ctx, &pubsub.Message{ Data: []byte(fmt.Sprintf(`{"shipment_id":"shp_1","status":%q,"seq":%d}`, status, seq+1)), OrderingKey: "shp_1", }) if _, err := res.Get(ctx); err != nil { // After a failed publish the client pauses this key until it is resumed. pub.ResumePublish("shp_1") log.Fatalf("publish %s: %v", status, err) } } }

Without EnableMessageOrdering, the Go client rejects messages that carry an OrderingKey, so a forgotten flag fails loudly instead of silently dropping order. The subscription side is one setting, --enable-message-ordering on gcloud pubsub subscriptions create or enable_message_ordering = true in Terraform, and because it cannot be changed later, an existing unordered subscription has to be replaced by a new one.

Redelivery and dead-letter topics

Ordering does not change Pub/Sub's at-least-once delivery, and it adds a twist: when a message is redelivered because its ack deadline expired or an ack was lost, Pub/Sub also redelivers every later message for that key, including ones already acknowledged. A handler that processes in_transit twice after delivered must not move the shipment backwards, so ordered handlers need idempotency as much as unordered ones, usually by storing the last applied sequence number per key.

A message that keeps failing blocks its key: later messages for the same key wait behind it. Unacknowledged messages can also delay other keys during server restarts or traffic shifts, which is why Google recommends a dead-letter topic on ordered subscriptions so a poisoned message cannot hold a key forever. The cost is that order is not guaranteed once messages go to the dead-letter topic, so a replay has to account for events that may now be older than what the key has since processed.

How does Encore handle ordering keys?

Encore

Encore brings infrastructure from code to Google Cloud: topics and subscriptions are declared in Go, and when the app deploys to your GCP project, Encore creates them with a dead-letter topic for each subscription, as the GCP infrastructure docs describe. Ordering is one field on the topic: OrderingAttribute names a message attribute, and the Pub/Sub docs explain that messages with the same value are delivered in publish order.

Set up the app

Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create logistics --example=hello-world$ cd logistics && mkdir -p shipments/migrations
-- shipments/migrations/1_create_shipments.up.sql CREATE TABLE shipments ( id TEXT PRIMARY KEY, status TEXT NOT NULL, last_seq BIGINT NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT now() );
// shipments/shipments.go package shipments import ( "context" "time" "encore.dev/beta/errs" "encore.dev/pubsub" "encore.dev/rlog" "encore.dev/storage/sqldb" ) var db = sqldb.NewDatabase("shipments", sqldb.DatabaseConfig{Migrations: "./migrations"}) type StatusChanged struct { ShipmentID string `json:"shipment_id" pubsub-attr:"shipment_id"` Status string `json:"status"` Seq int64 `json:"seq"` // increases per shipment, set by the publisher } // On GCP: a topic with message ordering, ordering key = the shipment_id attribute. var StatusTopic = pubsub.NewTopic[*StatusChanged]("shipment-status", pubsub.TopicConfig{ DeliveryGuarantee: pubsub.AtLeastOnce, OrderingAttribute: "shipment_id", }) var _ = pubsub.NewSubscription(StatusTopic, "project-shipment-status", pubsub.SubscriptionConfig[*StatusChanged]{ Handler: applyStatus, RetryPolicy: &pubsub.RetryPolicy{ MinBackoff: 5 * time.Second, MaxBackoff: time.Minute, MaxRetries: 5, }, }) // Ordering keeps events for one shipment in publish order, and redelivery is // still possible, so the write only applies events newer than the stored one. func applyStatus(ctx context.Context, e *StatusChanged) error { res, err := db.Exec(ctx, ` INSERT INTO shipments (id, status, last_seq) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE SET status = EXCLUDED.status, last_seq = EXCLUDED.last_seq, updated_at = now() WHERE shipments.last_seq < EXCLUDED.last_seq`, e.ShipmentID, e.Status, e.Seq) if err != nil { return err // retried before any later event for this shipment } if res.RowsAffected() == 0 { rlog.Info("stale or duplicate event skipped", "shipment", e.ShipmentID, "seq", e.Seq) } return nil } type PublishParams struct { ShipmentID string `json:"shipment_id"` Status string `json:"status"` Seq int64 `json:"seq"` } //encore:api private method=POST path=/shipments/status func Publish(ctx context.Context, p *PublishParams) error { if p.ShipmentID == "" || p.Seq <= 0 { return &errs.Error{Code: errs.InvalidArgument, Message: "shipment_id and a positive seq are required"} } _, err := StatusTopic.Publish(ctx, &StatusChanged{ShipmentID: p.ShipmentID, Status: p.Status, Seq: p.Seq}) return err }

On GCP, the Go runtime turns on ordering for the topic's publisher and sends each message with the shipment_id attribute's value as its ordering key, and when a publish fails it resumes the key before returning the error, so the caller can retry. Publishing without the attribute, or with an empty value, returns an InvalidArgument error rather than sending an unordered message. A handler that returns an error is retried before any later message for that shipment is delivered, and after MaxRetries the message moves to the dead-letter topic and the next one for the key is delivered, which is why the retry policy here is short.

The upsert makes redelivery harmless: it only applies an event whose seq is greater than the stored one. Run against Postgres 17 with the events 1, 2, 2, 3, 2, 4, 3, the duplicates and the stale ones changed no rows and the shipment ended at delivered with last_seq 4. Ordering has no effect during local development, so encore run will not reproduce the ordering behaviour, and the sequence check is what keeps the handler correct there too.

Best fit: teams on GCP that need per-entity order for events and want the topic, ordering, retries and dead-letter topic declared in Go next to the handler.

How to choose a key and a design

Use ordering keys when consumers apply state transitions or changes to the same entity and a reorder would produce a wrong result. Keep the key per entity, so one slow entity holds back only itself, and keep payloads small, since 1 MBps per key is the ceiling. Carry a sequence number or version in each message and make handlers ignore anything not newer, which covers redelivery, replays from the dead-letter topic and any publisher that retries. Where only the final state matters and events carry full state with a timestamp or version, the version check alone can be enough, and an unordered subscription scales further.

Frequently asked questions

How do ordering keys work in Pub/Sub?

Messages published with the same ordering key, from the same region, are delivered in publish order to subscriptions that have message ordering enabled. Messages with different keys, or with no key, have no ordering between them. The subscription setting can only be chosen when the subscription is created.

What do I need to enable Pub/Sub message ordering?

Three things: set an ordering key on each message, enable ordering on the publisher client (EnableMessageOrdering in Go), and create the subscription with message ordering enabled. Publish all messages for a key in one region, for example through a regional endpoint, since ordering is only guaranteed within a publish region.

Does Pub/Sub ordering guarantee exactly-once processing?

No. Delivery is still at least once, and when a message is redelivered, Pub/Sub also redelivers the later messages for that key, even ones already acknowledged. Handlers should be idempotent, for example by storing a per-key sequence number and ignoring events that are not newer.

How does Encore handle Pub/Sub ordering?

Set OrderingAttribute on an Encore topic to the name of a pubsub-attr field. On GCP, Encore publishes with that attribute's value as the ordering key, and a failed message for a key is retried before later messages for the same key, then goes to the dead-letter topic once retries run out. Ordering has no effect in local development.

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