Atomic operations

Better Auth 1.7 requires every database adapter to implement two atomic primitives, and calls them on paths you are almost certainly using:

Postgres: one guarded SQL statementCopy Anchor Link

On Postgres, eligible collections and supported predicates run as one guarded SQL statement over Payload's existing Drizzle connection:

• consumeOne uses DELETE … RETURNING, returning the row only to the caller whose statement removed it.
• incrementOne uses UPDATE … SET counter = COALESCE(counter, 0) + delta … RETURNING, so concurrent increments accumulate without a read-then-write race.

Both statements select at most one identity and re-assert the caller's guard on the outer write, where Postgres rechecks it after waiting for a concurrent writer. A guard miss returns null. No migration is required.

Since 0.14.2. Earlier releases used the Local API path on every database.

The atomicWrites policyCopy Anchor Link

payloadAdapter({
  payloadClient: payload,
  adapterConfig: { atomicWrites: 'auto' }, // default
})

• Payload's default beforeDuplicate hooks on unique fields don't disqualify a collection; they never run on update or delete.
• On the Payload 4 line, generated collections set authorship: false to keep injected createdBy/updatedBy hooks from disabling atomic writes. Re-enabling authorship through customizeCollection restores those hooks and the default policy's Local API fallback. See the Payload 4 upgrade note.
• Admin baseFilter / baseListFilter don't apply to these Local API operations and don't disqualify atomic writes.
• Virtual, join and ui fields have no stored columns and are ignored in the column checks.
• The policy inspects the sanitized collection config once per collection and caches the decision for the adapter instance, so configure collections before using the adapter.

LoggingCopy Anchor Link

• Policy refusals (in 'auto' and 'always') always console.warn once per collection and distinct reason.
• SQL compatibility failures (missing connection, table or column metadata; unsupported stored fields or writes; untranslatable predicates) always console.error once per collection and distinct reason. 'auto' then uses the Local API; 'always' throws.
• With enableDebugLogs: true, the adapter also logs the first atomic execution and first fallback per collection.

Under 'always', a predicate shape introduced by a future Better Auth release that the adapter can't translate will throw until the adapter is patched. That is why 'auto' is the default.

Supported shapesCopy Anchor Link

Supported predicates are scalar eq, ne, lt, lte, gt, gte and scalar-array in, with the usual AND/OR grouping and explicit NULL semantics. Nested paths, JSON predicates, insensitive mode and other operators are not supported. Unsupported stored shapes (such as localized or has-many fields) are not supported either. Both log an error and fall back in 'auto', or throw in 'always'.

Malformed IDs fail closed. Invalid UUIDs and non-numeric serial primary or relationship IDs never match, including for ne, so an invalid exclusion can't broaden a credential write to every non-null row. This is stricter than Payload's query builder, which validates primary-key UUIDs but passes relationship UUIDs through. Explicit null keeps its existing semantics.

Local API fallback and its limitCopy Anchor Link

Other databases (MongoDB, SQLite), and any collection or request that falls back, use the Local API:

• consumeOne reads the row, then deletes it by id. The row is returned only if this call's delete removed it; if a concurrent caller got there first, Payload raises a 404 and the adapter returns null.
• incrementOne reads the row, then writes with a guard that re-asserts Better Auth's precondition (for example remaining > 0) and the counter values the write was computed from. A racing writer's update matches no row, so the loser re-reads and retries (up to five attempts) instead of overwriting the winner.

DependencyCopy Anchor Link

drizzle-orm is a regular dependency pinned to 0.45.2, matching Payload 3.92.1, and installs with the package. Static imports keep the atomic SQL path in production Next.js, Vercel and standalone bundles without runtime adapter discovery. A test compares the pin with the installed dev Payload, and a daily canary compares it with the latest published @payloadcms/drizzle requirement and opens an issue on drift.

CI runs a real Postgres 17 integration suite for both UUID and serial IDs: concurrent increments, single-use consumption, OAuth refresh-token guards, malformed identifiers, row-shape parity, and Better Auth's ten-failure TOTP lockout.