DynamoDB Uniqueness on Multiple Attributes
DynamoDB guarantees uniqueness for exactly one thing: the primary key. There is
no UNIQUE (email) constraint, no UNIQUE (username), and nothing that spans
two attributes. Coming from SQL, that absence is the first surprise, and the
first place people ship a race condition.
How do you enforce a unique constraint on multiple attributes in DynamoDB?
DynamoDB has no UNIQUE constraint beyond the primary key, so you enforce uniqueness yourself: model each protected value as its own marker item whose key is that value, then write the record and every marker together in one TransactWriteItems, each put guarded by attribute_not_exists.
- Normalize before you key. Lowercase and trim the email first, or
Ada@Lovelace.ioclaims a second lock next toada@lovelace.io. - Read the failure by position.
CancellationReasonstells you which value was taken, so the user gets a field-level error. - Locks have a lifecycle. Email changes and account deletes are transactions too, or a stale lock blocks the value forever.
- Each signup costs 6 write units (three transactional writes of up to 1 KB), even when it's rejected.
Why the obvious approach is wrong
The instinct is to Query (or worse, Scan) for the email, see nothing, then
PutItem the new account. That's a check-then-act race.
Two people register ada@lovelace.io at the same millisecond. Both reads return
empty. Both writes succeed. You now have two accounts on one email, and nothing
in the table flags it.
A GSI on email doesn't save you either. GSIs are
eventually consistent, so the read
that gates your write can be stale by design. Make the write itself fail on a
taken value.
Model each constraint as a marker item
The engine already enforces one uniqueness rule for free: you can't write two items with the same key. So encode every uniqueness rule as a key.
Alongside the real account item, write one marker item per protected attribute. The marker's partition key is the namespaced value. If the value is taken, the key exists, and a guarded put can't overwrite it.
For a signup that must keep both email and username unique, three items move
together, keyed in a single-table layout (see
single-table design):
| Item | PK | SK | Purpose |
|---|---|---|---|
| Account record | ACCT#a1f9c3 | PROFILE | The real account |
| Email lock | UNIQ#EMAIL#ada@lovelace.io | LOCK | Reserves the email |
| Username lock | UNIQ#HANDLE#ada | LOCK | Reserves the username |
The account's own PK is a generated id (ACCT#a1f9c3), never the email, so
the user can change their email later without rewriting the primary key.
Build each lock key from the normalized value (trimmed, lowercased email; the handle in whatever case-folding your product promises).
Each lock carries
one attribute, owner, naming the account that holds it, so you can trace and
safely delete it later.
Write all three atomically
TransactWriteItems
applies up to 100 writes as one all-or-nothing unit. Guard each put with
attribute_not_exists(PK) so it fails if that key is already present.
If any one condition fails (the email lock, the handle lock, or the account
itself), DynamoDB rolls the whole transaction back and throws
TransactionCanceledException. No partial signup, no orphaned lock.
{
"TransactItems": [
{
"Put": {
"TableName": "accounts",
"Item": {
"PK": {"S": "ACCT#a1f9c3"},
"SK": {"S": "PROFILE"},
"email": {"S": "ada@lovelace.io"},
"username": {"S": "ada"}
},
"ConditionExpression": "attribute_not_exists(PK)"
}
},
{
"Put": {
"TableName": "accounts",
"Item": {
"PK": {"S": "UNIQ#EMAIL#ada@lovelace.io"},
"SK": {"S": "LOCK"},
"owner": {"S": "ACCT#a1f9c3"}
},
"ConditionExpression": "attribute_not_exists(PK)"
}
},
{
"Put": {
"TableName": "accounts",
"Item": {
"PK": {"S": "UNIQ#HANDLE#ada"},
"SK": {"S": "LOCK"},
"owner": {"S": "ACCT#a1f9c3"}
},
"ConditionExpression": "attribute_not_exists(PK)"
}
}
]
}The condition is the entire mechanism. Without attribute_not_exists, a second
signup with the same email silently overwrites the first lock. With it, the put
refuses, the transaction cancels, and your app surfaces "email already in use."
Each transactional write of an item up to 1 KB costs 2 write units, so a signup costs 6, and AWS bills it "even when the transaction is canceled". Every rejected duplicate costs the same 6.
The DynamoDB Expression Builder emits the
condition and the typed Item for each put. It doesn't build transactions, so
paste each put into your TransactItems array.
Read the failure, don't guess at it
When the transaction is canceled, DynamoDB returns a CancellationReasons array
in request order, one entry per item, None for an item with no error.
Counting from 0, a ConditionalCheckFailed at index 1 means the email is taken; index 2
means the username is. When both are taken, both report.
Map the index back to a field-level error instead of a generic "signup failed."
Inspect a lock
The marker items are invisible in your app's UI; they're plumbing. When a signup
fails and you need to know whether a lock exists, read it by its exact key:
a strongly consistent GetItem on
{PK: "UNIQ#EMAIL#ada@lovelace.io", SK: "LOCK"}.
The account and its locks have three different partition keys, so no single
read returns them together. A Query needs an exact partition key and can't
match the UNIQ# prefix.
To audit every lock, Scan with FilterExpression: begins_with(PK, :uniq). That
reads and bills the whole table, so run it as an occasional job, not on a request
path.
In DynoTable, type the exact lock key into the partition-key filter
and it runs a Query for that one item, owner attribute included.

Move the locks with every change and delete
Locks aren't write-once. They mirror the live value, so every operation that touches a protected attribute is a transaction too.
- Change email. One transaction: put the new
UNIQ#EMAIL#…lock withattribute_not_exists(PK), delete the old lock with the condition#owner = :acct(owneris a reserved word, so map#ownerto it), update the account. The owner check stops you deleting a lock another account now holds. - Delete account. Delete the account item and both lock items in one transaction, each lock delete guarded by the same owner condition.
- Retry safely. Resending a signup that already committed fails all three
conditions and reports a false conflict. Pass a stable
ClientRequestToken(the signup request id) and resend the identical request, including the sameACCT#id. DynamoDB treats that repeat within 10 minutes as the same call and returns success; a changed request under the same token fails withIdempotentParameterMismatchException.
If a lock still outlives its account (a delete that skipped the transaction),
find it with the audit scan above, GetItem each owner, and delete any lock
whose account is gone, again with the owner condition.
Next steps
Uniqueness markers are a single-table pattern, so they sit naturally next to your
other items. Read single-table design for the key
layout, and Query vs Scan for why a lock check is
a key lookup, never a Scan.
Draft the condition-guarded puts with the DynamoDB Expression Builder, then try DynoTable to inspect the lock items in your own table.


