Atomic Database Operations#

Better Auth exposes three database-level primitives — consumeOne, incrementOne, and reserveVerificationValue — that provide race-safe single-row mutations without application-layer locking. They are defined on the DBAdapter interface and are always present on the factory-wrapped adapter; adapters that don't implement them natively receive a transaction-based fallback automatically 1.

consumeOne — Atomic Single-Use Token Consumption#

consumeOne deletes a single matching row and returns it, or returns null if no row matched. Under concurrent invocation exactly one caller receives the row; every racer gets null 1.

The higher-level consumeVerificationValue on InternalAdapter wraps consumeOne inside a transaction with a per-key in-process mutex (withVerificationConsumeLock), cleans up stale siblings, and handles the secondary-storage path via secondaryStorage.getAndDelete when available. All downstream state changes must be gated on a non-null return value 1.

Callers:

• Email OTP — atomicVerifyOTP calls consumeVerificationValue; concurrent racers receive null → INVALID_OTP. Wrong codes recreate the row with an incremented attempt counter; after 3 failures (default) the row stays consumed 1.
• Phone OTP — same pattern; racers are rejected with INVALID_OTP 1.
• 2FA challenge — consumeVerificationValue(signedTwoFactorCookie) is called before issuing a session, preventing replay 1.
• WebAuthn challenges — consumed on first use 1.
• Password reset — consumeVerificationValue("reset-password:{token}") atomically deletes the token; expired or already-used tokens return null → INVALID_TOKEN 2.

Adapter fallback: factory wraps findMany + deleteMany in a transaction, re-applying the original where plus the matched row's id as a compare-and-swap guard. See factory.ts L1370–1416 1.

incrementOne — Atomic Guarded Counter Update#

incrementOne applies field = field + delta to a single row only while the where clause still matches. The predicate acts as both row selector and invariant guard — encoding constraints like remaining > 0 or count < max directly in the atomic SQL statement. Returns the updated row, or null if the guard failed 1.

Callers:

• Core rate limiter — two incrementOne calls in rate-limiter/index.ts L169–205: window reset (guarded on lastRequest <= data.lastRequest) and in-window increment (guarded on count < max) 3.
• API key quota — consumeRemaining decrements remaining by 1 guarded on remaining > 0; null → USAGE_EXCEEDED 3.
• API key rate limit — consumeRateLimit sequences start / reset / increment / deny decisions, each backed by a guarded incrementOne; on guard failure the row is re-fetched and the function retries recursively 3.
• OAuth refresh token rotation — CAS-style incrementOne marks a token revoked while minting its successor; a concurrent redeemer receives invalid_grant 1.
• Invitation acceptance — updateInvitation with fromStatus: "pending" compiles to UPDATE … SET status = 'accepted' WHERE id = ? AND status = 'pending' RETURNING *; only one concurrent acceptor wins 4.

Adapter fallback: wraps findMany + updateMany in a transaction, re-applying the original where predicates on the write. See factory.ts L1529–1585 1.

reserveVerificationValue — First-Writer-Wins Tombstoning#

reserveVerificationValue attempts to INSERT a marker row exactly once, returning true if this caller created it, false if a row for the same identifier already existed 1.

The reservation key is a deterministic SHA-256 hash of "reserve:" + identifier (base64url-encoded); the primary key constraint rejects duplicates. A failed create triggers a re-read to distinguish a race loss (row exists → false) from a genuine error (row absent → re-throw) 1.

Use cases: SAML assertion IDs, JWT jti replay protection, or any nonce that must be accepted exactly once.

Caveat: the secondary-storage-only path (storeInDatabase: false) has no primary key uniqueness guarantee and is best-effort under concurrency; a FIXME in the source marks this for future tightening. Additionally, reserveVerificationValue's secondary-storage write path lacks the if (ttl > 0) guard that is present in createVerificationValue and updateVerificationByIdentifier, which can cause unintended behavior when TTL is zero or negative 1.

Adapter Portability and Known Gaps#

consumeOne and incrementOne are optional on CustomAdapter but always present on the factory-wrapped DBAdapter. They are tracked for promotion to required in a future release 1.

Drizzle / PostgreSQL atomicity gap (fixed in PR #11331): The Drizzle adapter previously used a SELECT … LIMIT 1 subquery inside the UPDATE's WHERE IN (…) without repeating the guard on the UPDATE itself. Under PostgreSQL READ COMMITTED, two concurrent writers could both select the same row ID and both succeed, violating the one-winner contract. PR #11331 fixed this by repeating the original where conditions on the UPDATE statement, so PostgreSQL rechecks the guard after waiting for a concurrent writer 5. MySQL remains handled with an explicit SELECT … FOR UPDATE transaction path 4.

consumeVerificationValue secondary storage: Without getAndDelete, the fallback get + delete cannot coordinate across processes; a FIXME tracks making getAndDelete required in a future breaking release 1.

API key secondary storage: claimUsageInSecondaryStorage is a non-atomic read-modify-write. Use storage: "database" or fallbackToDatabase: true for strict quota/rate-limit enforcement 3.

Key Source References#