MongoDB Adapter#
The Better Auth MongoDB adapter (@better-auth/mongo-adapter) bridges Better Auth's generic DB adapter interface to MongoDB. Unlike relational adapters, it requires no schema generation or migrations — MongoDB's flexible document model handles structure automatically.
Package: @better-auth/mongo-adapter
Entry point: packages/mongo-adapter/src/index.ts
Main implementation: packages/mongo-adapter/src/mongodb-adapter.ts
Setup#
Install and wire up the adapter by passing a Db instance (and optionally a MongoClient) to mongodbAdapter:
import { betterAuth } from "better-auth";
import { MongoClient } from "mongodb";
import { mongodbAdapter } from "better-auth/adapters/mongodb";
const client = new MongoClient("mongodb://localhost:27017/database");
const db = client.db();
export const auth = betterAuth({
database: mongodbAdapter(db, { client }),
});
The db argument is required; everything else is optional config.
MongoDBAdapterConfig Options#
Defined at mongodb-adapter.ts:33–61:
| Option | Type | Default | Description |
|---|---|---|---|
client | MongoClient | undefined | Enables session-based transactions. Omit for standalone MongoDB without a replica set. |
transaction | boolean | true (when client provided) | Set to false on standalone instances that don't support replica-set transactions. |
usePlural | boolean | false | Use pluralized collection names (e.g. users instead of user). |
debugLogs | DBAdapterDebugLogOption | false | Emit adapter-level debug logs. |
⚠️ If your MongoDB instance is a standalone server (no replica set), you must set
transaction: false, otherwise operations will fail.
Database Capability Flags#
Capability flags tell the Better Auth core how to handle type coercion. They are defined in the adapter factory config interface and the MongoDB adapter sets them at mongodb-adapter.ts:669–682:
| Flag | MongoDB value | Framework default | Meaning |
|---|---|---|---|
supportsArrays | true | false | MongoDB stores arrays natively — no serialization to/from strings. |
supportsNumericIds | false | true | MongoDB uses ObjectId/UUID, not auto-increment integers. |
supportsJSON | (not set) | false | Core handles JSON ↔ string translation. MongoDB's document model stores objects natively, but the adapter relies on the framework default here. |
supportsDates | (not set) | true | MongoDB natively stores Date objects, so the default (true) is correct — no string conversion needed. |
supportsBooleans | (not set) | true | MongoDB stores booleans natively; default is correct. |
supportsUUIDs | (not set) | false | Framework does not assume native UUID support; the adapter handles UUID↔string conversion in its custom transform functions. |
ID Handling#
MongoDB's primary key field is _id, not id. The adapter transparently maps between them using mapKeysTransformInput / mapKeysTransformOutput , so the rest of the codebase always sees an id string.
Custom transform functions (customTransformInput / customTransformOutput) convert string IDs to ObjectId or UUID instances on write and back to strings on read. The ID type is controlled by options.advanced.database.generateId:
- Default →
ObjectId "uuid"→UUID
Transactions#
Transaction support is opt-in. When a MongoClient is supplied and transaction is not explicitly false, the adapter starts a MongoDB session and wraps operations in startTransaction / commitTransaction / abortTransaction.
For standalone MongoDB (no replica set), pass { transaction: false } to skip transactions and run operations sequentially instead.
Query Builders#
Case-insensitive string operators (used by the framework's where API) are implemented in query-builders.ts using MongoDB $regex with the i option. Functions include insensitiveEq, insensitiveIn, insensitiveNotIn, insensitiveContains, insensitiveStartsWith, and insensitiveEndsWith.
Experimental Joins#
Since version 1.4.0, the adapter supports database-level joins, which can provide 2–3× performance improvements on endpoints like /get-session and /get-full-organization. Enable via:
export const auth = betterAuth({
experimental: { joins: true },
});