SurrealDB Adapter for Better Auth

The most reliable bridge between SurrealDB and Better Auth.

This adapter is built to leverage the best of both worlds: SurrealDB's multi-model power and Better Auth's flexible authentication lifecycle. It is designed with a focus on security, efficiency, and zero-compromise integration.

Tip

🚀 Get your database running in seconds for free! Need a managed SurrealDB instance? Sign up through our referral link to get free cloud hosting credits and instant access to a high-performance database. It's a great way to support this project while starting yours at no cost!

---

Why this adapter?

Built with real-world scenarios in mind, this adapter goes beyond simple CRUD operations to ensure a seamless developer experience:

• Best of Both Worlds: Merges SurrealDB’s unique data structures with Better Auth's comprehensive ecosystem.
• Production Ready: Handles complex edge cases, such as polymorphic accountId mapping (Records vs. Strings), ensuring your schema stays valid.
• Unintrusive: We don't take over your database instance. Managing the connection and SurrealDB client remains entirely in your hands.
• Fully Compatible: Built to match the behavior of official adapters while providing community-driven optimizations.
• CLI Integrated: Full support for Better Auth CLI schema generation.

---

Key Features

• Secure Execution: Powered by surql tagged templates for safe, parameterized queries.
• Polymorphic Intelligence: Smartly distinguishes between native RecordId (Credentials) and string (OAuth) for the accountId field.
• Structural Integrity: Uses native SurrealDB RecordId for relations wherever possible.
• Atomic Transactions: Fully compatible with SurrealDB SDK's transaction lifecycle.
• CLI Schema Support: Generate your entire SurrealQL schema with a single command.
• Developer Experience: Optional, colorized console logs for every SurrealQL query sent to the DB.

---

Requirements

• Bun: >= 1.3.10 (or Node.js: >= 22.0.0)
• Better Auth: ^1.7.2
• SurrealDB JS SDK: ^2.0.8
• SurrealDB Server: v3.0.0+

---

Quick Start

1. Installation

bun add surreal-better-auth

Other package managers:

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

2. Configure Better Auth

// lib/auth.ts
import { betterAuth } from "better-auth";
import { surrealdbAdapter } from "surreal-better-auth";
import { db } from "./db"; // Your SurrealDB client instance

export const auth = betterAuth({
  // Whenever possible, always prefer ws over http for surrealdb instances.
  database: surrealdbAdapter(db, {
    // ID strategy: "ULID", "UUIDv4", "UUIDv7", or "guid"
    idGenerator: "guid",
   
   // Schema mode: "schemaless" or "schemafull", Default: "schemafull"
   schemaMode: "schemaless", 
    
    // Use plural table names (e.g., "users") if required by your schema
    usePlural: false,      
    
    // Enable colorized query logging for easier debugging
    logSurrealQL: true   
    
  }),
  // The rest of better-auth configuration
  emailAndPassword: { enabled: true }
  // ...
});

3. Generate & Import Schema

Use the Better Auth CLI to generate your SurrealQL definitions:

bunx @better-auth/cli generate --output schema.surql --config src/lib/server/auth.ts

• When prompted, save the output as schema.surql in your project root.
• Import the schema into your SurrealDB instance:

  surreal import --conn http://localhost:8000 --user root --pass topSecretPassword --ns project --db auth schema.surql

  Note: You can also use Surreal Studio or any other method to import the generated schema.

4. Support development & maintenance

• Star the project on GitHub
• Sponsor the development to help keep the project maintained. You will also get a banner on this repository.

---

Best Practices & Architecture

Database Isolation

For better security and organization, we recommend isolating auth data into a dedicated database within your namespace:

• Namespace: my_project
• Database: auth (separate from your main business logic database)

Row-Level Security (RLS)

To implement native SurrealDB Row-Level Security based on the authenticated user, use the Better Auth JWT Plugin. This enables you to pass the authentication context directly to SurrealDB via tokens, allowing you to define powerful PERMISSIONS on your tables.

---

Show Your Support

If this adapter helps your project, please consider:

• ⭐ Starring the project on GitHub
• 💖 Sponsoring the development to help keep the project maintained.

Development & Testing

This monorepo includes comprehensive testing to ensure the adapter works reliably:

Quick Commands

# Install dependencies
bun install

# Build the adapter
bun run build

# Run adapter unit tests
bun run test:adapter

# Run integration tests (requires SurrealDB)
bun run test:integration

# Run all tests
bun run test:all

# Start example app
bun run dev

Adapter License

surreal-better-auth package - MIT License - see LICENSE for details.

---

Links

• 📖 better-auth Documentation
• 🗄️ SurrealDB Documentation
• 🌟 Try SurrealDB Cloud (Free tier + welcome bonus!)
• 🐙 GitHub Repository
• 📦 NPM Package

---

Made with for the SurrealDB and Better Auth communities