PostgreSQL

PostgreSQL 是一个功能强大的开源关系型数据库管理系统，以其高级特性、可扩展性以及对复杂查询和大型数据集的支持而闻名。阅读更多关于 PostgreSQL 的信息。

示例用法

确保你已安装并配置好 PostgreSQL。然后，你可以直接将其连接到 Better Auth。

auth.ts

import { betterAuth } from "better-auth";
import { Pool } from "pg";

export const auth = betterAuth({
  database: new Pool({
    connectionString: "postgres://user:password@localhost:5432/database",
  }),
});

更多信息请阅读 Kysely 关于 PostgresDialect 的文档。

模式生成与迁移

Better Auth CLI 允许你根据 Better Auth 的配置和插件生成或迁移数据库模式。

PostgreSQL 模式生成	PostgreSQL 模式迁移
✅ 支持	✅ 支持

npx auth@latest migrate

npx auth@latest generate

连接查询（实验性）

当 Better-Auth 需要在单个查询中从多个表获取相关数据时，数据库连接查询非常有用。类似 /get-session、/get-full-organization 等端点极大地受益于此功能，根据数据库延迟，性能可提升 2 到 3 倍。

Kysely PostgreSQL 方言自 1.4.0 版本起原生支持连接查询。要启用此功能，需要在 auth 配置中将 experimental.joins 选项设为 true。

auth.ts

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  experimental: { joins: true }
});

启用此功能后，可能需要执行数据库迁移。

使用非默认模式

在大多数情况下，默认模式是 public。若希望 Better Auth 使用非默认模式（例如 auth）存放其表，有几种方式：

Option 1: Set search_path in connection string (Recommended)

在连接 URI 后追加 options 参数：

auth.ts

import { betterAuth } from "better-auth";
import { Pool } from "pg";

export const auth = betterAuth({
  database: new Pool({
    connectionString: "postgres://user:password@localhost:5432/database?options=-c search_path=auth",
  }),
});

需要时请进行 URL 编码：?options=-c%20search_path%3Dauth。

Option 2: Set search_path using Pool options

auth.ts

import { betterAuth } from "better-auth";
import { Pool } from "pg";

export const auth = betterAuth({
  database: new Pool({
    host: "localhost",
    port: 5432,
    user: "postgres",
    password: "password",
    database: "my-db",
    options: "-c search_path=auth",
  }),
});

选项 3：为数据库用户设置默认模式

设置 PostgreSQL 用户的默认模式：

ALTER USER your_user SET search_path TO auth;

设置后需要重新连接以应用更改。

先决条件

使用非默认模式之前，请确保：

该模式已存在：
```
CREATE SCHEMA IF NOT EXISTS auth;
```

用户具备相应权限：

GRANT ALL PRIVILEGES ON SCHEMA auth TO your_user;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA auth TO your_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA auth GRANT ALL ON TABLES TO your_user;

工作原理

Better Auth CLI 迁移系统会自动检测你配置的 search_path：

运行 npx auth migrate 时，它只会检查你配置模式中的表
其他模式中的表（例如 public）会被忽略，从而避免冲突
所有新表都会在你指定的模式中创建

故障排查

问题： 迁移期间出现 "relation does not exist" 错误

解决方案： 这通常意味着该模式不存在，或者用户没有权限。请按上文所示创建模式并授予权限。

验证你的模式配置：

你可以通过检查 search_path 来确认 Better Auth 将使用哪个模式：

SHOW search_path;

这应该返回你的自定义模式（例如 auth）作为第一个值。

其他信息

PostgreSQL 的支持是通过 Kysely 适配器实现的，Kysely 支持的任何数据库也均受支持。(点击这里了解更多)

如果你在寻求性能提升或优化技巧，可以查看我们的性能优化指南。

On this page