Intermediate8 min read

Singleton Items in DynamoDB

A singleton item is a single row with a fixed, hardcoded key that holds state for your whole application: one record, not one per user or per document. It's what a relational app keeps in a one-row settings table.

Coming from SQL, you'd reach for a config table with id = 1 and a SELECT * FROM config. In DynamoDB you do the same thing with a hardcoded partition key, and because you always know that key, you read it with a GetItem, not a Query or a Scan.

What is a singleton item in DynamoDB?

A singleton item is a single DynamoDB row stored under a fixed, hardcoded key that holds global state for your whole application, such as feature flags or a config blob. Because you always know the key, you read it with a GetItem and update it with plus condition expressions.

  • A singleton is one item with a constant key. You hardcode the PK/SK in your code (e.g. SETTINGS#APP / FLAGS#V1) instead of templating in a user or document id.
  • Read it with GetItem, never Scan. You always know the full key, so a point read has a flat, predictable cost (at most 1 read unit for an item up to 4 KB).
  • It's a by definition. Every request can touch the same partition, so cache it and keep the item small; don't make it a write bottleneck.
  • Mutate it safely with update + condition expressions, not read-modify-write in your app, where the lost-update race lives.

Recognize the pattern

You have global state when the data isn't scoped to any one entity. A few tells:

  • A flag that's the same for everyone (signup_enabled = false).
  • A blob of tunables your app reads on boot (rate limits, default quotas).
  • A version number for the whole system, not per-row.

Anything scoped to a user, tenant, or document is not a singleton: that's an ordinary item keyed by that entity's id. The singleton is the leftover global slice that has nowhere else to live.

Give it a constant key

The whole pattern hinges on one decision. The key is a literal, not a template. For a global feature-flags item in an overloaded single table, pick a fixed prefix and a fixed value:

PKSKattributes
SETTINGS#APPFLAGS#V1signup_enabled, maintenance_mode, ai_search_enabled

PK = "SETTINGS#APP" and SK = "FLAGS#V1" are baked into the code, with no user id and no tenant id. The application asks for exactly this item every time, and a known key is a GetItem: the cheapest, most predictable read DynamoDB offers.

The V1 suffix is deliberate. If the flag schema changes shape later, you write a FLAGS#V2 item and flip readers over, instead of mutating the live one in place. Versioning the singleton key buys you a clean migration seam.

Read it with GetItem

Because the key is fully known, you never Query and you never Scan for a singleton. A Scan reads (and bills) the whole table, then discards what its filter doesn't match: the Scan footgun, for one row you can address directly.

A GetItem against SETTINGS#APP / FLAGS#V1 returns the flags in a single strongly or eventually consistent read. An item up to 4 KB costs 0.5 read units eventually consistent or 1 strongly consistent (DynamoDB read and write operations).

Those are read request units on on-demand and RCUs on provisioned capacity. Keep the singleton small and that cost stays flat; growing the config blob into a second 4 KB block doubles the billed read.

On the read path, when the app boots or a request lands, you GetItem the fixed key, you cache the result. The flow:

yesnoApp / requestGetItem PK=SETTINGS#APPSK=FLAGS#V1Item found?Use flags, cache locallyFall back to safe defaults

The fixed key turns a global lookup into one point read with a built-in default path.

Note the no branch: a missing singleton should never crash you. Default to the safe value (feature off, maintenance on) so a first-deploy gap or a bad key fails closed, not open.

Update it without a race

The trap is updating a singleton with read-modify-write in your app: you GetItem the flags, flip one in memory, then PutItem the whole thing back. Two concurrent writers both read the old item and the second Put clobbers the first's change. Lost update.

Two DynamoDB features stop the race without app-side locking:

To flip one flag, target just that attribute with a SET and guard it with a revision bump so concurrent writers can't trample each other:

# UpdateItem
Key                  PK=SETTINGS#APP  SK=FLAGS#V1
UpdateExpression     SET signup_enabled = :on, revision = :next
ConditionExpression  revision = :current

If two writers race, the second one's revision = :current check fails with ConditionalCheckFailedException.

Nothing retries it for you: your code re-reads the item and tries again. Pass ReturnValuesOnConditionCheckFailure: ALL_OLD and the error carries the current item, which saves the re-read.

You can scaffold the names, values, and this expression shape in the DynamoDB Expression Builder before wiring it into code. For a deeper look at the operators, see the update-expression idioms guide.

Mind the hot key

A singleton is, by construction, a hot key: every part of your app may read the same partition. That's fine for reads if you cache, and it's the main risk of the pattern.

One item tops out at a partition's 3,000 read units and 1,000 write units per second: about 6,000 eventually consistent GetItems per second of an item up to 4 KB. Physical partitions covers the limits.

  • Cache aggressively. Read the flags once per process (or per N seconds), not on every request. The singleton's value is the cheapest thing to memoize.
  • Keep writes rare. A flag toggled by an admin a few times a day is nothing. A singleton you increment on every request hits the 1,000 writes/s ceiling.
  • Keep it small. Read cost scales with item size in 4 KB blocks. A bloated config blob makes every boot more expensive than it needs to be.

For a high-write global counter, use a sharded counter instead. Pick N from peak writes per second ÷ 1,000.

Write each increment as UpdateItem ADD #n :1 on a random partition key COUNTER#GLOBAL#0..N-1, and read all N keys with one BatchGetItem and sum them. Atomic counters covers the ADD increment, and hot partitions covers write sharding.

Singleton vs per-entity item

The line is what the data is scoped to.

Singleton itemPer-entity item
KeyHardcoded constant (SETTINGS#APP)Templated with an id (USER#42)
How manyExactly oneOne per user / document / tenant
Typical readGetItem on the known keyGetItem or Query by entity
ScopeWhole applicationA single entity
Use forGlobal flags, config, system versionProfiles, documents, anything per-id

If you find yourself wanting two singletons of the same kind, you don't have a singleton. You have a per-entity item, and the entity is the thing you forgot to key by (per-tenant config, say).

Pitfalls and next steps

Address it by key, write it with update + condition expressions, default safely when it's missing, and keep high-frequency writes off it.

The singleton lives comfortably inside a single-table design: it's one more item collection with a fixed key alongside your entity rows.

Try DynoTable to browse your table, find the singleton row by its fixed key, and, on a paid plan, edit flags by hand while you build the write path.

By Dmitriy · Updated