---
title: "Transactions & limitations"
description: "How the @surrealdb/better-auth adapter handles transactions, and the current limitations to be aware of."
canonical_url: "https://surrealdb.com/docs/integrate/integrations/authentication/better-auth/transactions-and-limitations"
section: "Better Auth"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Transactions & limitations

How the @surrealdb/better-auth adapter handles transactions, and the current limitations to be aware of.

The `@surrealdb/better-auth` adapter uses transactions internally, and exposes them for operations you want to group yourself. This page covers that behaviour and the limitations that come with it.

## Transactions

Transaction support is built in. Better Auth uses transactions internally for operations that need atomicity (for example, creating a session alongside a new user record), so most applications never call the transaction API directly.

If you need manual transaction access, call `transaction` on the adapter. Operations run inside the callback are committed together when it resolves, or discarded if it throws.

```typescript
const adapter = surrealAdapter({ db })(options);

await adapter.transaction(async (trx) => {
    await trx.create({ model: 'user', data: { /* ... */ } });
    await trx.create({ model: 'session', data: { /* ... */ } });
});
```

Transactions are backed by [`SurrealDB.beginTransaction()`](/docs/reference/query-language/statements/begin.md). If any operation inside the callback throws, the transaction is cancelled and changes are discarded.

`beginTransaction()` needs a WebSocket connection, so connect the `db` that you give the adapter with a `ws://` or `wss://` URL. Over HTTP, `beginTransaction()` throws `UnsupportedFeatureError`, and every Better Auth operation that uses a transaction fails, such as signing up a user. On Cloudflare Workers, open the connection inside each request. See [Cloudflare Workers](/docs/learn/querying/concepts-and-guides/connecting-from-serverless-and-edge.md#cloudflare-workers).

## Limitations

Keep the following in mind when adopting the adapter.

### Version coupling

The adapter targets **Better Auth 1.6.x** and **SurrealDB 3.1+**. Other major versions of either dependency are not supported.

### Numeric identifiers are not supported

By default Better Auth uses string identifiers, and [UUIDs](/docs/integrate/integrations/authentication/better-auth/overview.md#identifiers) can be enabled in your Better Auth configuration. Numeric (auto-increment) identifier strategies are **not** supported, because SurrealDB does not generate them natively and the adapter has no JavaScript fallback for them.

### `SCHEMAFULL` schemas require regeneration

With the default `schemaMode: 'schemafull'`, writes to fields that are not in the generated schema are rejected. Whenever you add a plugin or otherwise introduce new fields, [regenerate and reapply the schema](/docs/integrate/integrations/authentication/better-auth/getting-started.md#schema-generation). If you would rather not regenerate each time, set `schemaMode: 'schemaless'`; known fields stay typed and indexed, and writes to undeclared fields are accepted.

### Transaction rollback is best-effort

SurrealDB's `cancel()` is not honoured in every setup (for example, the in-memory engine). To keep rollback reliable, the adapter compensates by deleting records it created inside a failed transaction. This covers records created during the transaction; it does not restore prior values for records that were updated or deleted within it.

### Value deserialisation

When reading records, the adapter converts SurrealDB types back to JavaScript values: a `datetime` becomes a JavaScript `Date`, and a `RecordId` becomes its string `id`. Bear this in mind if you query the underlying tables directly rather than through Better Auth.
