How to use the authenticated db for querying?

[hgoona]

Hi @oskar-gmerek , great adaptor!

I'm trying to get my head around the way better-auth likes to do things and I'm wondering if I've missed something:
When the user goes through the sign in process and has entered the secured part of the app, is there a surreal db connection authenticated with the user's credential, that the user can therefore use to make queries with?

Previously I had setup auth without better-auth and of sign up user with root permission db connection (server side only) , then sign in with a db instance that retains the user credentials - so that their queries follow the rbac policy setup on each table etc.

Is something like this available via this adaptor, or is it done in a different way? Would be grateful for a minimum example, eg. how a signed in user can securely do a form action query to surrealdb?

NOTE: I've already successfully got the base setup of better-auth and this adaptor fully working. Just unsure about the above pattern for db querying.

[oskar-gmerek]

Hi @hgoona ! Thanks for bringing this up. To be honest, I’m surprised it took this long for someone to ask this, as it's a crucial part of building scalable apps.

Clarifications

This adapter is designed to be highly adaptable to various scenarios and environments. However, it is intentionally a thin layer that translates better-auth queries into SurrealDB language and vice-versa. By design, it does not attempt to manage your database connection instance, leaving that flexibility to the developer.

The Path to a Solution

Since the adapter doesn't manage the connection, it cannot provide the "authenticated connection" out of the box, but it is built to work perfectly in such a scenario. You just need a few extra steps to bridge the two.

There are several ways to achieve this, but the most robust one (which I recommend) involves using JWTs and JWKS.

To trigger SurrealDB's built-in RLS, you need a JWT token that SurrealDB trusts. You can issue this token via better-auth using the JWT Plugin.

The Setup Pattern

1. On the Better-Auth side:

• Enable the JWT Plugin.
• Modify the JWT payload to include claims required by SurrealDB (like ns, db, and ac). See SurrealDB JWT documentation.
• Expose the JWKS endpoint. This is how SurrealDB will verify that the token was actually signed by your auth server.

2. On the SurrealDB side:

• Define an access method using TYPE JWT pointing to your better-auth JWKS URL:

  DEFINE ACCESS <access_name> ON DATABASE TYPE JWT URL "https://your-app.com/api/auth/jwks";

Once this is set up, when a user logs in, they get a JWT. You can then use this token to authenticate your SurrealDB client (db.authenticate(jwt)), and all your DEFINE TABLE ... PERMISSIONS will work automatically.

---

Pro-Tips for Architecture

I highly recommend the following structure for production apps:

1. Separate Databases: Create a dedicated database for authentication (e.g., ns: project, db: auth) and a separate one for your application data (ns: project, db: app).
2. Service Account for Better-Auth: Configure better-auth to connect using a dedicated database user restricted only to the auth database.
3. Application Access: For your application logic, connect to the app database. Users will authenticate via the JWT/JWKS method mentioned above.

Why this architecture?

• Separation of Concerns: Your auth logic and app logic live in different silos.
• Isolation: Critical session/user data is isolated from general application queries.
• Cleanliness: You don't clutter your main application database with internal better-auth tables.
• Flexibility: You can connect to the database from the client or server as needed. If you ever need to access auth data from your app logic, you can simply switch context using db.use({ ns: 'project', db: 'auth' }).

I don't have the capacity to create a full interactive example right now, but I would highly welcome any contributions to the documentation or examples folder regarding this pattern!

Note

On a side note, I have recently stabilized a new version of the adapter that supports SurrealDB v3+, SurrealDB SDK JS v2+, and the latest Better-Auth 1.5+. This version was rebuilt from scratch (leveraging only small parts of the original code) and includes several key optimizations that make it significantly better than v1.

While it still requires intensive testing before being officially labeled as "stable," I highly recommend using this version if you have the flexibility to experiment with it. It’s in a much better position architecturally than the previous release.

• Repository: https://github.com/oskar-gmerek/surreal-better-auth/tree/beta
• NPM Package: https://www.npmjs.com/package/surreal-better-auth/v/2.0.0-beta.8

I would be extremely grateful for any feedback, bug reports, or suggestions regarding this beta version!

[hgoona]

Hi @oskar-gmerek this sounds like an AI reply and doesn't seem correct. Do you mind reviewing? / clarifying?

[oskar-gmerek]

Hi @hgoona,

Hi @oskar-gmerek this sounds like an AI reply and doesn't seem correct. Do you mind reviewing? / clarifying?

Not an AI, just a maintainer who prefers to write detailed, structured answers. Let's get straight to the technical point.

To answer your question directly:
No, the adapter does not create user-authenticated DB connections.

You asked: "Is something like this available via this adaptor, or is it done in a different way?"

My previous answer was so extensive exactly because that "different way" requires a paradigm shift. Business data should be queried directly using the SurrealDB SDK, which can be authenticated with a JWT signed by better-auth or your app.

To help visualize this mental model without repeating the setup details from my first post, I've added a quick diagram and a summary below.

Click to expand: The JWT + RLS flow (Mental Model)

graph LR
    User -->|Login/Sign-up| BetterAuth[better-auth]
    BetterAuth -->|Generate| JWT[Session Token + JWT]
    JWT --> App[Your App]
    App -->|Authenticated Action + JWT| SurrealDB[SurrealDB]
    SurrealDB -->|RLS Check| Result{Result}
    Result -->|Authorized| Data[Return Data]
    Result -->|Unauthorized| Reject[Reject]

Loading

TL;DR:

• better-auth should use a SYSTEM USER authenticated connection for its internal/admin tasks.
• For user queries, your app should pass a JWT to SurrealDB, and you can define RLS policies based on the token's claims, regardless of where the user is stored.
• You don't need this adapter to work with SurrealDB or to utilize its RLS system. This adapter is mainly helpful if you don't want to extend your stack with an additional database like PostgreSQL, or for more advanced use cases.

Just unsure about the above pattern for db querying.

Regarding the db querying pattern: that part should be implemented completely outside of this adapter. To clarify the responsibilities: better-auth simply provides a way (via the JWT plugin) to pass user identity to SurrealDB, while this adapter ensures that better-auth properly stores its own internal data in SurrealDB.