Overview

Better Auth is a comprehensive, framework-agnostic authentication and authorisation library for TypeScript. The @surrealdb/better-auth adapter lets you use SurrealDB as the database behind Better Auth: you pass it a single connected Surreal client and Better Auth manages all of its table operations through the adapter.

The adapter supports schema generation, transactions, the full set of Better Auth WHERE operators, and every Better Auth plugin.

Prerequisites

• SurrealDB 3.1 or later

• Better Auth 1.6.x

• Node.js 18+ or Bun 1.x

Feature support

The adapter advertises the following capabilities to Better Auth:

Identifiers

By default, Better Auth generates string identifiers in JavaScript. The adapter stores them as SurrealDB record IDs and deserialises them back to strings when reading, so a record round-trips to your application as the plain string id.

UUIDs are also supported. Enable them in your Better Auth configuration:

betterAuth({
    database: surrealAdapter({ db }),
    advanced: { database: { generateId: 'uuid' } },
});

Better Auth generates the UUID in JavaScript and passes it to the adapter, which stores and reads it transparently (it round-trips as the plain UUID string). SurrealDB does not mint the UUID natively, which is why the adapter reports supportsUUIDs: false to Better Auth: that flag means "the database generates UUIDs itself", not "UUIDs are unsupported".

Numeric (auto-increment) identifiers are not supported.

In this section

Sources

• GitHub repository

• npm package

• Better Auth documentation