PostgreSQL

PostgreSQL 是一个功能强大的开源关系型数据库管理系统，以其先进的功能、可扩展性以及对复杂查询和大数据集的支持而闻名。 在这里了解更多信息 here。

【PostgreSQL is a powerful, open-source relational database management system known for its advanced features, extensibility, and support for complex queries and large datasets. Read more here.】

示例用法

【Example Usage】

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

【Make sure you have PostgreSQL installed and configured. Then, you can connect it straight into Better Auth.】

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

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

架构生成与迁移

【Schema generation & migration】

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

【The Better Auth CLI allows you to generate or migrate your database schema based on your Better Auth configuration and plugins.】

npx @better-auth/cli@latest generate

npx @better-auth/cli@latest migrate

联接（实验性）

【Joins (Experimental)】

当 Better-Auth 需要在单个查询中从多张表获取相关数据时，数据库连接（joins）非常有用。像 /get-session、/get-full-organization 等端点以及许多其他端点都极大地受益于这一功能，根据数据库延迟的不同，性能提升可达 2 到 3 倍。

【Database joins is useful when Better-Auth needs to fetch related data from multiple tables in a single query. Endpoints like /get-session, /get-full-organization and many others benefit greatly from this feature, seeing upwards of 2x to 3x performance improvements depending on database latency.】

自 1.4.0 版本起，Kysely PostgreSQL 方言原生支持连接（joins）。 要启用此功能，你需要在身份验证配置中将 experimental.joins 选项设置为 true。

【The Kysely PostgreSQL dialect supports joins out of the box since version 1.4.0. To enable this feature, you need to set the experimental.joins option to true in your auth configuration.】

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

使用非默认模式

【Use a non-default schema】

在大多数情况下，默认的模式是 public。如果希望 Better Auth 为其表使用非默认模式（例如 auth），你有几种选择：

【In most cases, the default schema is public. To have Better Auth use a non-default schema (e.g., auth) for its tables, you have several options:】

选项 1：在连接字符串中设置 search_path（推荐）

【Option 1: Set search_path in connection string (Recommended)】

将 options 参数附加到你的连接 URI：

【Append the options parameter to your connection URI:】

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。

【URL-encode if needed: ?options=-c%20search_path%3Dauth.】

选项 2：使用连接池选项设置 search_path

【Option 2: Set search_path using Pool options】

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：为数据库用户设置默认模式

【Option 3: Set default schema for database user】

设置 PostgreSQL 用户的默认模式：

【Set the PostgreSQL user's default schema:】

ALTER USER your_user SET search_path TO auth;

设置完成后，请重新连接以应用更改。

【After setting this, reconnect to apply the changes.】

先决条件

【Prerequisites】

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

【Before using a non-default schema, ensure:】

1. 模式已存在：

   CREATE SCHEMA IF NOT EXISTS auth;

2. 用户具有适当的权限：

   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;

它是如何工作的

【How it works】

更佳认证 CLI 迁移系统会自动检测你配置的 search_path：

【The Better Auth CLI migration system automatically detects your configured search_path:】

• 运行 npx @better-auth/cli migrate 时，它只检查你配置的 schema 中的表
• 其他模式（例如 public）中的表会被忽略，以防止冲突
• 所有新表都会在你指定的模式中创建

故障排除

【Troubleshooting】

SHOW search_path;

附加信息

【Additional Information】

PostgreSQL 在底层通过 Kysely 适配器得到支持，Kysely 支持的任何数据库也同样得到支持。(在这里了解更多)

如果你正在寻找性能改进或技巧，请查看我们的 性能优化指南。