Rate Limiting Concurrency Control#

Better Auth enforces rate limits under concurrent load using optimistic concurrency control — no application-layer locks, no queuing. The mechanism centers on the incrementOne database primitive, whose WHERE clause acts as both a row selector and an invariant guard evaluated inside a single atomic SQL write. If the guard no longer holds when the write lands, the operation returns null and the caller retries. 1

This pattern is used in two locations:

The incrementOne Primitive#

incrementOne 2 applies field = field + delta to a single row only while the WHERE clause still matches. The where array accepts comparison operators (gt, lt, lte, eq), so range invariants like remaining > 0 or count < max are evaluated inside the same atomic SQL statement — two concurrent callers cannot both observe count < max and both increment past the limit. Returns the updated row, or null if the guard matched nothing. 3

Adapter fallback: incrementOne is optional on CustomAdapter but always present on the factory-wrapped DBAdapter. Adapters without a native implementation receive a transaction-based fallback that wraps findOne + updateMany, re-applying the original where predicates as a compare-and-swap guard, with up to five retries before throwing on contention 4 5.

Core Rate Limiter (rate-limiter/index.ts)#

The createDatabaseStorageWrapper function drives two guarded incrementOne calls per request:

1. Window reset — when timeSinceLastRequest >= windowInMs, an incrementOne with set: { count: 1, lastRequest: now } is guarded on lastRequest <= data.lastRequest 6. This ensures only one concurrent caller resets the window counter; others fall through to a recursive retry.

2. In-window increment — within a window, count += 1 is guarded on lastRequest > windowStart AND count < max 7. A null return triggers a re-read and recursive consume() call.

Fresh key creation uses db.create instead of incrementOne. If the insert fails (unique constraint from a concurrent opener), the code re-reads and retries — ensuring one request opens the window and the rest are counted 8.

bigint normalization: After reading a row, readRow coerces data.lastRequest from JavaScript bigint to Number if needed — PostgreSQL bigint columns can surface this type at runtime 9.

API Key Rate Limiting (verify-api-key.ts)#

Quota: consumeRemaining#

consumeRemaining handles keys with a finite remaining counter via two sequential guarded writes:

1. Refill CAS — if a refill interval has elapsed, incrementOne guarded on id AND lastRefillAt = <observed value> resets remaining to refillAmount - 1. Only one concurrent caller wins; others fall through to the plain decrement 10.
2. Guarded decrement — incrementOne with { remaining: -1 } guarded on remaining > 0. A null return means quota is exhausted → USAGE_EXCEEDED 11.

Rate Limit: consumeRateLimit#

consumeRateLimit first calls evaluateRateLimit to produce one of five decisions (skip, start, reset, increment, deny), then maps each to a guarded write:

Recursive retry: when any incrementOne returns null (guard raced), the code re-fetches the row and calls consumeRateLimit recursively 12 13. This handles both window-roll races and burst races.

Secondary Storage Caveat#

When API keys use storage: "secondary-storage" without fallbackToDatabase, quota and rate-limit consumption goes through claimUsageInSecondaryStorage — a non-atomic read-modify-write. Two concurrent requests can both read the same snapshot and both succeed. A FIXME comment tracks backing this with an atomic SecondaryStorage.increment. 1

The core rate limiter's secondary-storage path uses SecondaryStorage.increment (which creates the counter with a fixed TTL on first use) and is atomic by design 14.

For strict quota and rate-limit enforcement, use storage: "database" or storage: "secondary-storage" with fallbackToDatabase: true.