# MongoDB 适配器 (/docs/adapters/mongo)

将 Better Auth 与 MongoDB 集成。



MongoDB 是一种流行的 NoSQL 数据库，广泛用于构建可扩展且灵活的应用程序。它提供了灵活的模式，便于数据建模和查询。

在开始之前，请确保您已安装并配置好 MongoDB。更多信息，请参见 [MongoDB 文档](https://www.mongodb.com/docs/)

## 安装 [#安装]

要使用 MongoDB 适配器，您需要安装 `@better-auth/mongo-adapter` 包：

<CodeBlockTabs defaultValue="npm" groupId="persist-install">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install @better-auth/mongo-adapter
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @better-auth/mongo-adapter
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @better-auth/mongo-adapter
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @better-auth/mongo-adapter
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## 示例用法 [#示例用法]

### 副本集或分片集群 [#副本集或分片集群]

传入 `client`，适配器便会默认使用事务。副本集或分片集群请使用相应的连接字符串：

```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { MongoClient } from "mongodb";
import { mongodbAdapter } from "@better-auth/mongo-adapter";

const client = new MongoClient("mongodb://localhost:27017/database");
const db = client.db();

export const auth = betterAuth({
  database: mongodbAdapter(db, {
    client,
  }),
});
```

发生并发写入同一文档时，MongoDB 会因写冲突中止其中一个事务，并要求应用重试。适配器最多重试此类事务 120 秒，因此在竞争激烈时，请求可能耗时更长，而不是直接失败。要缩短此上限，可在 `MongoClient` 上设置 `timeoutMS`；该选项也会影响此客户端上的所有其他操作。

重试会重新执行整个操作，包括 `before` [数据库钩子](/docs/concepts/database#database-hooks)以及接收事务的插件回调。应在 `after` 钩子中发送邮件和调用其他服务；该钩子只会在提交后运行一次。

### 独立服务器 [#独立服务器]

独立 MongoDB 服务器不支持事务。使用 `MongoClient` 创建 `db`，并在不传入 `client` 选项的情况下将其传给适配器：

```ts title="auth.ts"
import { betterAuth } from "better-auth";
import { MongoClient } from "mongodb";
import { mongodbAdapter } from "@better-auth/mongo-adapter";

const client = new MongoClient("mongodb://localhost:27017/database");
const db = client.db();

export const auth = betterAuth({
  database: mongodbAdapter(db),
});
```

不使用事务时，如果后续写入失败，先前的写入可能仍会保留。迁移到副本集或分片集群后，传入 `client` 即可启用事务。请参阅 [MongoDB 的事务要求](https://www.mongodb.com/docs/manual/core/transactions-production-consideration/#availability)。

## 模式生成与迁移 [#模式生成与迁移]

对于 MongoDB，我们不需要生成或迁移模式。

## 联接 [#联接]

当 Better-Auth 需要通过单个查询从多个表中获取相关数据时，数据库联接非常有用。像 `/get-session`、`/get-full-organization` 以及许多其他端点都能从此功能中大幅受益，根据数据库延迟的不同，性能提升可达 2 倍至 3 倍。

MongoDB 适配器从版本 `1.4.0` 开始开箱即用地支持联接。要启用此功能，请在您的 auth 配置中将 `advanced.database.joins` 设置为 `true`。

```ts title="auth.ts"
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  advanced: {
    database: {
      joins: true,
    },
  },
});
```

## 更多信息 [#更多信息]

* 如果您正在寻找性能改进或优化建议，请查看我们的 <Link href="/docs/guides/optimizing-for-performance">性能优化</Link>指南。