Advanced6 min read

DynamoDB Uniqueness on Multiple Attributes

DynamoDB guarantees uniqueness for exactly one thing: the . 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 , 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.io claims a second lock next to ada@lovelace.io.
  • Read the failure by position. CancellationReasons tells 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 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):

ItemPKSKPurpose
Account recordACCT#a1f9c3PROFILEThe real account
Email lockUNIQ#EMAIL#ada@lovelace.ioLOCKReserves the email
Username lockUNIQ#HANDLE#adaLOCKReserves 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.

DynoTable looking up one email lock by its exact partition key, with the owner attribute that ties it to an account.
DynoTable looking up one email lock by its exact partition key, with the owner attribute that ties it to an account.

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 with attribute_not_exists(PK), delete the old lock with the condition #owner = :acct (owner is a reserved word, so map #owner to 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 same ACCT# id. DynamoDB treats that repeat within 10 minutes as the same call and returns success; a changed request under the same token fails with IdempotentParameterMismatchException.

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.

By Dmitriy · Updated