SurrealDB Adapter for Better Auth

1.0.0 · active · verified Wed Apr 22

This package provides an official adapter for integrating SurrealDB with the Better Auth authentication library. It enables `better-auth` to persist user and session data within a SurrealDB instance, leveraging its capabilities for authentication flows. The current stable version is `1.0.0`, with a `2.0.0-beta` series actively under development, indicating a continuous release cadence. A key differentiator is its compliance with `better-auth`'s `createAdapter` utility, ensuring full compatibility with core features like CLI-based schema generation. It also offers advanced ID generation options, including `sdk.UUIDv4` and `sdk.UUIDv7`, providing flexibility in how records are identified within SurrealDB. The library is designed for modern JavaScript/TypeScript environments, requiring Node.js >=20.0.0 or Bun >=1.2.0, and relies on peer dependencies for `surrealdb` and `better-auth`.

Common errors

```
Error: Peer dependency 'surrealdb' not found. Please install it.
```
cause The `surrealdb` package is a peer dependency and must be installed separately.

fix npm install surrealdb
```
Error: Peer dependency 'better-auth' not found. Please install it.
```
cause The `better-auth` package is a peer dependency and must be installed separately.

fix npm install better-auth
```
TypeError: Cannot read properties of undefined (reading 'signin') at initializeAuth
```
cause The SurrealDB `db` object was not correctly initialized or connected, or the `signin` call failed.

fix Verify your SurrealDB server is running and accessible at the specified endpoint (e.g., `ws://localhost:8000/rpc`). Check your `db.signin` credentials and ensure they have database access.
```
Error: Adapter initialization failed: Missing `db` instance.
```
cause The `createSurrealDBAdapter` function was called without a valid SurrealDB instance.

fix Pass an initialized and connected `Surreal` client instance as the first argument to `createSurrealDBAdapter(db, options)`.

Warnings

breaking Version `1.0.0` introduced 'Official Adapter Compliance' by using `better-auth`'s `createAdapter` utility. This might break integrations that relied on older, non-compliant adapter interfaces from pre-1.0 beta versions.
Fix: Ensure your adapter implementation or instantiation aligns with the `createAdapter` utility from `better-auth` as shown in the package's documentation. Review your adapter configuration for `idGenerator` options.
gotcha The package currently has an active `2.0.0-beta` release line. While these betas often contain new features like 'bypass ruleset', they might also introduce API changes or instability not present in the stable `1.0.0` release. Always consult the specific beta changelogs.
Fix: For production applications, it is generally recommended to stick to the latest stable release (v1.0.0) unless the beta features are critical and their potential for breaking changes is accepted. When using a beta, pin the exact version.
gotcha The adapter requires an active SurrealDB connection and appropriate permissions (signin/signup) to perform database operations. Misconfigured permissions or an unauthenticated database connection will lead to failures.
Fix: Ensure your SurrealDB instance is running, accessible, and the `db.signin` or `db.signup` calls are correctly executed with sufficient privileges for the database operations the adapter performs (e.g., creating/reading users and sessions).
gotcha The `idGenerator` option, while flexible, needs careful consideration. Using `sdk.UUIDv4` or `sdk.UUIDv7` is recommended for SurrealDB. Custom generators must return unique IDs compatible with SurrealDB's record ID format.
Fix: If implementing a custom `idGenerator`, ensure it produces unique and valid SurrealDB record IDs. For most cases, `sdk.UUIDv7` is a good default choice for its ordered nature.

Install

npm install surreal-better-auth npm
yarn add surreal-better-auth yarn
pnpm add surreal-better-auth pnpm

Imports

createSurrealDBAdapter
wrong:
```
import SurrealDBAdapter from 'surreal-better-auth';
```
correct:
```
import { createSurrealDBAdapter } from 'surreal-better-auth';
```
The adapter is exported as a named function, not a default export. Ensure to destructure it correctly.
SurrealDBAdapterOptions
wrong:
```
import { SurrealDBAdapterOptions } from 'surreal-better-auth';
```
correct:
```
import type { SurrealDBAdapterOptions } from 'surreal-better-auth';
```
This is a TypeScript type; use `import type` for clarity and bundler optimization, though `import` also works.
BetterAuthAdapter
```
import type { BetterAuthAdapter } from 'better-auth';
```
While this type comes from 'better-auth', it's crucial for type-checking the adapter's return value.

Quickstart

This quickstart demonstrates how to initialize the `surreal-better-auth` adapter with a SurrealDB instance and integrate it into `better-auth`, configuring it with UUIDv7 for ID generation.

import { createSurrealDBAdapter } from 'surreal-better-auth';
import { BetterAuth } from 'better-auth';
import { Surreal } from 'surrealdb';

async function initializeAuth() {
  const db = new Surreal('ws://localhost:8000/rpc');
  // Ensure you've signed in or created a scope/database for the adapter
  await db.signin({
    user: process.env.SURREAL_USER ?? 'root',
    pass: process.env.SURREAL_PASS ?? 'root',
  });
  await db.use('test', 'test');

  const adapter = createSurrealDBAdapter(db, {
    idGenerator: 'sdk.UUIDv7', // Use UUIDv7 for better indexing and time-based ordering
    // You can also define custom ID generation logic here
  });

  const betterAuth = new BetterAuth(adapter);

  console.log('BetterAuth initialized with SurrealDB adapter.');
  // Example: You can now use betterAuth to manage users, sessions, etc.
  // const newUser = await betterAuth.createUser({ email: 'test@example.com', password: 'password123' });
  // console.log('Created user:', newUser);

  // Cleanup (optional)
  // await db.close();
}

initializeAuth().catch(console.error);

view raw JSON →