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 update plus condition expressions.
- A singleton is one item with a constant key. You hardcode the
PK/SKin your code (e.g.SETTINGS#APP/FLAGS#V1) instead of templating in a user or document id. - Read it with
GetItem, neverScan. 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 hot key 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:
| PK | SK | attributes |
|---|---|---|
| SETTINGS#APP | FLAGS#V1 | signup_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:
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:
- Update expressions mutate one attribute server-side, leaving the rest
untouched. No need to re-
Putthe whole item. - Condition expressions make the write succeed only if the item still looks
the way you expect, so a stale write is rejected with
ConditionalCheckFailedException(AWS condition expression docs).
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 item | Per-entity item | |
|---|---|---|
| Key | Hardcoded constant (SETTINGS#APP) | Templated with an id (USER#42) |
| How many | Exactly one | One per user / document / tenant |
| Typical read | GetItem on the known key | GetItem or Query by entity |
| Scope | Whole application | A single entity |
| Use for | Global flags, config, system version | Profiles, 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.