![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/hero.webp?raw=true\")
\n \n \n
![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/atom.png?raw=true\")
SurrealDB Adapter for Better Auth ![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/question.png?raw=true\")
Why this adapter?\n\nBuilt with real-world scenarios in mind, this adapter goes beyond simple CRUD operations to ensure a seamless developer experience:\n\n- **Best of Both Worlds:** Merges SurrealDB’s unique data structures with Better Auth's comprehensive ecosystem.\n- **Production Ready:** Handles complex edge cases, such as polymorphic `accountId` mapping (Records vs. Strings), ensuring your schema stays valid.\n- **Unintrusive:** We don't take over your database instance. Managing the connection and SurrealDB client remains entirely in your hands.\n- **Fully Compatible:** Built to match the behavior of official adapters while providing community-driven optimizations.\n- **CLI Integrated:** Full support for Better Auth CLI schema generation.\n\n---\n\n## ![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/crown.png?raw=true\")
Key Features\n\n- **Secure Execution:** Powered by `surql` tagged templates for safe, parameterized queries.\n- **Polymorphic Intelligence:** Smartly distinguishes between native `RecordId` (Credentials) and `string` (OAuth) for the `accountId` field.\n- **Structural Integrity:** Uses native SurrealDB `RecordId` for relations wherever possible.\n- **Atomic Transactions:** Fully compatible with SurrealDB SDK's transaction lifecycle.\n- **CLI Schema Support:** Generate your entire SurrealQL schema with a single command.\n- **Developer Experience:** Optional, colorized console logs for every SurrealQL query sent to the DB.\n\n---\n\n## ![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/requirements.png?raw=true\")
Requirements\n\n- **Bun**: >= 1.3.10 (or **Node.js**: >= 22.0.0)\n- **Better Auth**: ^1.7.2\n- **SurrealDB JS SDK**: ^2.0.8\n- **SurrealDB Server**: v3.0.0+\n\n---\n\n## ![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/quick.png?raw=true\")
Quick Start\n\n### 1. Installation\n\n```bash\nbun add surreal-better-auth\n```\n*Other package managers:*\n```bash\nnpm install surreal-better-auth\npnpm add surreal-better-auth\nyarn add surreal-better-auth\n```\n\n### 2. Configure Better Auth\n\n```typescript\n// lib/auth.ts\nimport { betterAuth } from \"better-auth\";\nimport { surrealdbAdapter } from \"surreal-better-auth\";\nimport { db } from \"./db\"; // Your SurrealDB client instance\n\nexport const auth = betterAuth({\n // Whenever possible, always prefer ws over http for surrealdb instances.\n database: surrealdbAdapter(db, {\n // ID strategy: \"ULID\", \"UUIDv4\", \"UUIDv7\", or \"guid\"\n idGenerator: \"guid\",\n \n // Schema mode: \"schemaless\" or \"schemafull\", Default: \"schemafull\"\n schemaMode: \"schemaless\", \n \n // Use plural table names (e.g., \"users\") if required by your schema\n usePlural: false, \n \n // Enable colorized query logging for easier debugging\n logSurrealQL: true \n \n }),\n // The rest of better-auth configuration\n emailAndPassword: { enabled: true }\n // ...\n});\n```\n\n### 3. Generate & Import Schema\n\nUse the Better Auth CLI to generate your SurrealQL definitions:\n\n```bash\nbunx @better-auth/cli generate --output schema.surql --config src/lib/server/auth.ts\n```\n\n- When prompted, save the output as `schema.surql` in your project root.\n- Import the schema into your SurrealDB instance:\n ```bash\n surreal import --conn http://localhost:8000 --user root --pass topSecretPassword --ns project --db auth schema.surql\n ```\n *Note: You can also use **Surreal Studio** or any other method to import the generated schema.*\n\n### 4. Support development & maintenance\n - **Star the project** on [GitHub](https://github.com/oskar-gmerek/surreal-better-auth)\n - **[Sponsor the development](https://github.com/sponsors/oskar-gmerek)** to help keep the project maintained. You will also get a banner on this repository.\n---\n\n## ![\"surrealdb](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/brain.png?raw=true\")
Best Practices & Architecture\n\n### Database Isolation\nFor better security and organization, we recommend isolating auth data into a dedicated database within your namespace:\n- **Namespace:** `my_project`\n- **Database:** `auth` (separate from your `main` business logic database)\n\n### Row-Level Security (RLS)\nTo 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.\n\n---\n\n## ![\"better](\"https://github.com/oskar-gmerek/surreal-better-auth/blob/beta/assets/star.png?raw=true\")
Show Your Support\n\nIf this adapter helps your project, please consider:\n- ⭐ **Starring the project** on [GitHub](https://github.com/oskar-gmerek/surreal-better-auth)\n- 💖 **[Sponsoring the development](https://github.com/sponsors/oskar-gmerek)** to help keep the project maintained.\n","readmeFilename":"README.md"}