{"id":16690,"library":"surreal-better-auth","title":"SurrealDB Adapter for Better Auth","description":"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`.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/oskar-gmerek/surreal-better-auth","tags":["javascript","adapter","auth","authentication","database","better-auth","better-auth-adapter","surreal-better-auth","surrealdb-better-auth","typescript"],"install":[{"cmd":"npm install surreal-better-auth","lang":"bash","label":"npm"},{"cmd":"yarn add surreal-better-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add surreal-better-auth","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the underlying database client for SurrealDB operations.","package":"surrealdb","optional":false},{"reason":"Core authentication library that this package integrates with.","package":"better-auth","optional":false}],"imports":[{"note":"The adapter is exported as a named function, not a default export. Ensure to destructure it correctly.","wrong":"import SurrealDBAdapter from 'surreal-better-auth';","symbol":"createSurrealDBAdapter","correct":"import { createSurrealDBAdapter } from 'surreal-better-auth';"},{"note":"This is a TypeScript type; use `import type` for clarity and bundler optimization, though `import` also works.","wrong":"import { SurrealDBAdapterOptions } from 'surreal-better-auth';","symbol":"SurrealDBAdapterOptions","correct":"import type { SurrealDBAdapterOptions } from 'surreal-better-auth';"},{"note":"While this type comes from 'better-auth', it's crucial for type-checking the adapter's return value.","symbol":"BetterAuthAdapter","correct":"import type { BetterAuthAdapter } from 'better-auth';"}],"quickstart":{"code":"import { createSurrealDBAdapter } from 'surreal-better-auth';\nimport { BetterAuth } from 'better-auth';\nimport { Surreal } from 'surrealdb';\n\nasync function initializeAuth() {\n  const db = new Surreal('ws://localhost:8000/rpc');\n  // Ensure you've signed in or created a scope/database for the adapter\n  await db.signin({\n    user: process.env.SURREAL_USER ?? 'root',\n    pass: process.env.SURREAL_PASS ?? 'root',\n  });\n  await db.use('test', 'test');\n\n  const adapter = createSurrealDBAdapter(db, {\n    idGenerator: 'sdk.UUIDv7', // Use UUIDv7 for better indexing and time-based ordering\n    // You can also define custom ID generation logic here\n  });\n\n  const betterAuth = new BetterAuth(adapter);\n\n  console.log('BetterAuth initialized with SurrealDB adapter.');\n  // Example: You can now use betterAuth to manage users, sessions, etc.\n  // const newUser = await betterAuth.createUser({ email: 'test@example.com', password: 'password123' });\n  // console.log('Created user:', newUser);\n\n  // Cleanup (optional)\n  // await db.close();\n}\n\ninitializeAuth().catch(console.error);","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0-beta.1"},{"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).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"npm install surrealdb","cause":"The `surrealdb` package is a peer dependency and must be installed separately.","error":"Error: Peer dependency 'surrealdb' not found. Please install it."},{"fix":"npm install better-auth","cause":"The `better-auth` package is a peer dependency and must be installed separately.","error":"Error: Peer dependency 'better-auth' not found. Please install it."},{"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.","cause":"The SurrealDB `db` object was not correctly initialized or connected, or the `signin` call failed.","error":"TypeError: Cannot read properties of undefined (reading 'signin') at initializeAuth"},{"fix":"Pass an initialized and connected `Surreal` client instance as the first argument to `createSurrealDBAdapter(db, options)`.","cause":"The `createSurrealDBAdapter` function was called without a valid SurrealDB instance.","error":"Error: Adapter initialization failed: Missing `db` instance."}],"ecosystem":"npm"}