Prisma 配置参考

概述

Prisma 配置文件使用 TypeScript 配置 Prisma CLI，包括 migrate 和 studio 等子命令。

Prisma ORM v7 变更

从 Prisma ORM v7 开始，当您运行 prisma init 时，会自动创建一个 prisma.config.ts 文件。数据库连接 URL 现在在此文件中配置，而不是在 schema.prisma 文件中。有关设置详情，请参阅使用环境变量。

您可以通过以下两种方式定义配置

使用 defineConfig 助手

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: { 
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  datasource: { 
    url: env("DATABASE_URL") 
  }
});

使用 TypeScript 的 satisfies 运算符与 PrismaConfig 类型

import 'dotenv/config'
import type { PrismaConfig } from "prisma";
import { env } from "prisma/config";

export default {
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
    seed: 'tsx prisma/seed.ts',
  },
  datasource: { 
    url: env("DATABASE_URL") 
  }
} satisfies PrismaConfig;

配置接口

这是 PrismaConfig 类型的简化版本

export declare type PrismaConfig = {

  // Whether features with an unstable API are enabled.
  experimental: {
    externalTables: boolean;
  },

  // The path to the schema file, or path to a folder that shall be recursively searched for *.prisma files.
  schema?: string;

  // Configuration for Prisma migrations.
  migrations?: {
    path: string;
    seed: string;
    initShadowDb: string;
  };

  // Configuration for the database view entities.
  views?: {
    path: string;
  };

  // Configuration for the `typedSql` preview feature.
  typedSql?: {
    path: string;
  };
  
  // Database connection configuration
  datasource?: {
    url: string;
    shadowDatabaseUrl?: string;
  }
  
};

Prisma ORM v6.19 及更早版本

在 Prisma ORM v6.19 及更早版本中，配置接口还包括

experimental.adapter 和 experimental.studio 标志
用于配置驱动适配器的 adapter 属性
用于 Prisma Studio 配置的 studio 属性
用于直接数据库连接的 datasource.directUrl 属性
用于在 classic 和 js 引擎之间进行选择的 engine 属性

这些已在 Prisma ORM v7 中移除。有关迁移指南，请参阅下面的各个属性部分。

支持的文件扩展名

Prisma 配置文件可以命名为 prisma.config.* 或 .config/prisma.*，扩展名为 js、ts、mjs、cjs、mts 或 cts。支持其他扩展名以确保与不同的 TypeScript 编译器设置兼容。

选项参考

`schema`

配置 Prisma ORM 如何定位和加载您的 schema 文件。可以是文件或文件夹路径。相对路径相对于 prisma.config.ts 文件位置解析。有关 schema 位置选项的更多信息，请参阅此处。

属性	类型	必需	默认值
`schema`	`string`	否	`./prisma/schema.prisma` 和 `./schema.prisma`

`tables.external` 和 `enums.external`

这些选项声明了数据库中外部管理的表和枚举（非 Prisma Migrate 管理）。您仍然可以使用 Prisma Client 查询它们，但它们将被迁移忽略。

属性	类型	必需	默认值
`tables.external`	`string[]`	否	`[]`
`enums.external`	`string[]`	否	`[]`

示例

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
  experimental: {
    externalTables: true,
  },
  tables: {
    external: ["public.users"],
  },
  enums: {
    external: ["public.role"],
  },
});

在此处了解有关 externalTables 功能的更多信息。

`migrations.path`

Prisma 存储和查找迁移文件的目录路径。

属性	类型	必需	默认值
`migrations.path`	`string`	否	无

`migrations.seed`

此选项允许您定义一个脚本，Prisma 在运行迁移或使用 npx prisma db seed 命令后运行该脚本来填充数据库。该字符串应为可在终端中执行的命令，例如使用 node、ts-node 或 tsx。

属性	类型	必需	默认值
`migrations.seed`	`string`	否	无

示例

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx db/seed.ts',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

`migrations.initShadowDb`

此选项允许您定义 Prisma 在创建迁移之前在影子数据库上运行的 SQL 语句。它在处理外部管理表时很有用，因为 Prisma 需要了解这些表的结构才能正确生成迁移。

属性	类型	必需	默认值
`migrations.initShadowDb`	`string`	否	无

示例

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    initShadowDb: `
      CREATE TABLE public.users (id SERIAL PRIMARY KEY);
    `,
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
  experimental: {
    externalTables: true,
  },
  tables: {
    external: ["public.users"],
  },
});

在此处了解有关 externalTables 功能的更多信息。

`views.path`

Prisma 查找 SQL 视图定义的目录路径。

属性	类型	必需	默认值
`views.path`	`string`	否	无

`typedSql.path`

Prisma 查找用于通过typedSql生成类型的 SQL 文件的目录路径。

属性	类型	必需	默认值
`typedSql.path`	`string`	否	无

`experimental`

在 Prisma CLI 中启用特定的实验性功能。

属性	类型	必需	默认值
`externalTables`	`boolean`	否	`false`

示例

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
  experimental: {
    externalTables: true,
  },
});

注意

如果您在未启用实验性标志的情况下使用 externalTables 功能，Prisma 将抛出错误

Failed to load config file "~" as a TypeScript/JavaScript module. Error: Error: The `externalTables` configuration requires `experimental.externalTables` to be set to `true`.

Prisma ORM v6.19 及更早版本

在 Prisma ORM v6.19 及更早版本中，experimental 对象还包括 adapter 和 studio 标志。这些已在 Prisma ORM v7 中移除。有关详细信息，请参阅 adapter 和 studio 部分。

`datasource.url`

包含身份验证信息的连接 URL。大多数连接器使用数据库提供的语法。

Prisma ORM v7 变更

在 Prisma ORM v7 中，url 字段在 prisma.config.ts 中配置，而不是在 schema.prisma 文件的 datasource 块中。当您运行 prisma init 时，生成的 schema.prisma 文件将不包含 datasource 块中的 url 属性。

对于 Prisma ORM v6.19 及更早版本，url 字段保留在 schema.prisma 文件的 datasource 块中。

属性	类型	必需	默认值
`datasource.url`	`string`	是	`''`

示例

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

`datasource.shadowDatabaseUrl`

Prisma Migrate 使用的影子数据库的连接 URL。允许您使用云托管数据库作为影子数据库。

Prisma ORM v7 变更

在 Prisma ORM v7 中，shadowDatabaseUrl 字段在 prisma.config.ts 中配置，而不是在 schema.prisma 文件的 datasource 块中。

对于 Prisma ORM v6.19 及更早版本，shadowDatabaseUrl 字段保留在 schema.prisma 文件的 datasource 块中。

属性	类型	必需	默认值
`datasource.shadowDatabaseUrl`	`string`	否	`''`

`datasource.directUrl` (已移除)

在 Prisma ORM v7 中移除

datasource.directUrl 属性已在 Prisma ORM v7 中移除，取而代之的是 url 属性。

对于 Prisma ORM v6.19 及更早版本

用于直接连接数据库的连接 URL。

如果您在 url 参数中使用连接池 URL（例如 pgBouncer），则需要直接连接数据库的 Prisma CLI 命令将使用 directUrl 参数中的 URL。

Prisma Studio 从 5.1.0 版本开始支持 directUrl 属性。使用 Prisma Postgres 数据库时不需要 directUrl 属性。

属性	类型	必需	默认值
`datasource.directUrl`	`string`	否	`''`

`adapter` (已移除)

在 Prisma ORM v7 中移除

adapter 属性已在 Prisma ORM v7 中移除。从 Prisma ORM v7 开始，驱动程序适配器的迁移无需在 prisma.config.ts 中进行额外配置即可自动工作。

对于 Prisma ORM v6.19 及更早版本

一个函数，返回一个 Prisma 驱动程序适配器实例，Prisma CLI 使用该实例运行迁移。该函数应返回一个解析为有效 Prisma 驱动程序适配器的 Promise。

属性	类型	必需	默认值
`adapter`	`() => Promise<SqlMigrationAwareDriverAdapterFactory>`	否	无

使用 Prisma ORM D1 驱动程序适配器的示例

import path from "node:path";
import type { PrismaConfig } from "prisma";
import { PrismaD1 } from "@prisma/adapter-d1";

export default {
  experimental: {
    adapter: true
  },
  engine: "js",
  schema: path.join("prisma", "schema.prisma"),
  async adapter() {
    return new PrismaD1({
      CLOUDFLARE_D1_TOKEN: process.env.CLOUDFLARE_D1_TOKEN,
      CLOUDFLARE_ACCOUNT_ID: process.env.CLOUDFLARE_ACCOUNT_ID,
      CLOUDFLARE_DATABASE_ID: process.env.CLOUDFLARE_DATABASE_ID,
    });
  },
} satisfies PrismaConfig;

注意

从 Prisma ORM v6.11.0 开始，D1 适配器已从 PrismaD1HTTP 重命名为 PrismaD1。

`engine` (已移除)

在 Prisma ORM v7 中移除

engine 属性已在 Prisma ORM v7 中移除。

对于 Prisma ORM v6.19 及更早版本

配置您的项目应使用的 schema 引擎。

属性	类型	必需	默认值
`engine`	`classic` 或 `js`	否	`classic`

默认设置为使用 classic 引擎，这要求在您的 prisma.config.ts 中设置 datasource。

import 'dotenv/config'
import path from "node:path";
import { defineConfig, env } from "prisma/config";
export default defineConfig({
  engine: "classic",
  datasource: {
      url: env('DATABASE_URL'),
  },
  schema: path.join("prisma", "schema.prisma"),
});

`studio` (已移除)

在 Prisma ORM v7 中移除

studio 属性已在 Prisma ORM v7 中移除。要运行 Prisma Studio，请使用

npx prisma studio --config ./prisma.config.ts

Prisma Studio 现在会自动使用 datasource 属性中的连接配置。有关详细信息，请参阅 Prisma Studio 文档。

对于 Prisma ORM v6.19 及更早版本

配置 Prisma Studio 如何连接到您的数据库。有关详细信息，请参阅下面的子选项。

属性	类型	必需	默认值
`studio`	`object`	否	无

`studio.adapter` (已移除)

一个函数，返回一个 Prisma 驱动程序适配器实例。该函数接收一个包含环境变量的 env 参数，并应返回一个解析为有效 Prisma 驱动程序适配器的 Promise。

属性	类型	必需	默认值
`studio.adapter`	`(env: Env) => Promise<SqlMigrationAwareDriverAdapterFactory>`	否	无

使用 Prisma ORM LibSQL 驱动程序适配器的示例

import type { PrismaConfig } from "prisma";

export default {
  experimental: {
    studio: true
  },
  engine: "js",
  studio: {
    adapter: async (env: Env) => {
      const { PrismaLibSQL } = await import("@prisma/adapter-libsql");
      const { createClient } = await import("@libsql/client");

      const libsql = createClient({
        url: env.DOTENV_PRISMA_STUDIO_LIBSQL_DATABASE_URL,
      });
      return new PrismaLibSQL(libsql);
    },
  },
} satisfies PrismaConfig;

常见模式

设置您的项目

要开始使用 Prisma Config，请在项目根目录中创建 prisma.config.ts 文件。您可以使用以下任一方法

使用 defineConfig

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

使用 TypeScript 类型

import 'dotenv/config'
import type { PrismaConfig } from "prisma";
import { env } from "prisma/config";

export default {
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
} satisfies PrismaConfig;

使用环境变量

Prisma ORM v7 变更

在 Prisma ORM v7 中，当您运行 prisma init 时，生成的 prisma.config.ts 文件默认包含 import 'dotenv/config'。您必须安装 dotenv 包才能使用环境变量。

使用 prisma.config.ts 时，需要明确加载 .env 文件中的环境变量。根据您的运行时和 Node 版本，有几种方法

使用 dotenv（推荐用于 Prisma ORM v7）

安装 dotenv 包

npm install dotenv

在 prisma.config.ts 文件的顶部导入 dotenv/config

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  datasource: {
    url: env('DATABASE_URL'),
  },
});

使用 Node.js v20+ 或 tsx 结合 --env-file 标志

如果使用 Node.js v20+ 或 tsx，您可以传递 --env-file 标志来自动加载环境变量

tsx --env-file=.env src/index.ts
tsx watch --env-file=.env --env-file=.local.env src/index.ts
tsx --env-file=.env ./prisma/seed.ts

使用 Bun

对于 Bun，.env 文件无需额外配置即可自动加载。

类型安全的环境变量

使用 env() 助手函数提供对环境变量的类型安全访问

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

type Env = {
  DATABASE_URL: string
}

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: env<Env>('DATABASE_URL'),
  },
});

处理可选环境变量

prisma/config 中的 env() 助手函数如果指定的环境变量未定义，则会抛出错误。理解这一点很重要，因为

每个 Prisma CLI 命令都会加载 prisma.config.ts 文件
只有一些命令实际需要 datasource.url 值（例如，prisma db *、prisma migrate *、prisma generate --sql）
像 prisma generate 这样的命令不需要数据库 URL，但如果在加载配置文件时 env() 抛出错误，它仍然会失败

例如，如果您在未设置 DATABASE_URL 的情况下运行 prisma generate，并且您的配置使用 env('DATABASE_URL')，您将看到

Error: PrismaConfigEnvError: Missing required environment variable: DATABASE_URL

解决方案： 如果您的环境变量不保证存在（例如，在您只运行 prisma generate 进行类型检查的 CI/CD 管道中），请不要使用 env() 助手。相反，直接访问环境变量

import 'dotenv/config'
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
  },
  datasource: {
    url: process.env.DATABASE_URL!, // Or use: process.env.DATABASE_URL ?? '' to provide a fallback value
  },
});

注意

当您想强制环境变量存在时，使用 env() 助手。当变量可能可选，具体取决于运行的命令时，直接使用 process.env。

使用多文件 schema

如果您想将 Prisma schema 分割成多个文件，您需要通过 schema 属性指定 Prisma schema 文件夹的路径

import path from "node:path";
import type { PrismaConfig } from "prisma";

export default {
  schema: path.join("prisma", "schema"),
} satisfies PrismaConfig;

在这种情况下，您的 migrations 目录必须位于定义 datasource 块的 .prisma 文件旁边。

例如，假设 schema.prisma 定义了 datasource，以下是您需要放置 migrations 文件夹的方式

# `migrations` and `schema.prisma` are on the same level
.
├── migrations
├── models
│   ├── posts.prisma
│   └── users.prisma
└── schema.prisma

路径解析

Prisma CLI 命令（例如 prisma validate 或 prisma migrate）使用 prisma.config.ts（或 .config/prisma.ts）来定位您的 Prisma schema 和其他资源。

关键规则

配置文件中定义的路径（例如，schema、migrations）始终相对于配置文件所在的位置解析，而不是您运行 CLI 命令的位置。
CLI 必须首先找到配置文件本身，这取决于 Prisma 的安装方式和使用的包管理器。

与 `pnpm prisma` 的行为

当 Prisma 在本地安装并通过 pnpm prisma 运行时，无论您是从项目根目录还是子目录运行命令，配置文件都会自动检测到。

项目树示例

.
├── node_modules
├── package.json
├── prisma-custom
│   └── schema.prisma
├── prisma.config.ts
└── src

从项目根目录运行示例

pnpm prisma validate
# → Loaded Prisma config from ./prisma.config.ts
# → Prisma schema loaded from prisma-custom/schema.prisma

从子目录运行示例

cd src
pnpm prisma validate
# → Still finds prisma.config.ts and resolves schema correctly

与 `npm exec prisma` 或 `bun prisma` 的行为

通过 npm exec prisma 或 bun prisma 运行时，CLI 仅在命令从项目根目录（package.json 声明 Prisma 的位置）运行时才检测配置文件。

从项目根目录运行示例

npm exec prisma validate
# → Works as expected

从子目录运行（失败）

cd src
npm exec prisma validate
# → Error: Could not find Prisma Schema...

要解决此问题，您可以使用 --config 标志

npm exec prisma -- --config ../prisma.config.ts validate

全局 Prisma 安装

如果 Prisma 是全局安装的（npm i -g prisma），它可能默认找不到您的 prisma.config.ts 或 prisma/config 模块。为避免问题

优先在项目中进行本地 Prisma 安装。
或者在本地使用 prisma/config 并传递 --config 指向您的配置文件。

Monorepos

如果 Prisma 安装在工作区根目录，pnpm prisma 将从子目录检测配置文件。
如果 Prisma 安装在子包中（例如，./packages/db），请从该包目录或更深层运行命令。

自定义配置位置

您可以在运行 Prisma CLI 命令时为配置文件指定自定义位置

prisma validate --config ./path/to/myconfig.ts

加载环境变量

Prisma ORM v7 变更

在 Prisma ORM v7 中，prisma init 会自动生成 prisma.config.ts 文件。要使用 dotenv 加载环境变量，请执行以下操作

安装 dotenv 包。
在 prisma.config.ts 文件的顶部添加 import 'dotenv/config'。

这是 Prisma 读取 .env 文件中的值所必需的。

要在您的 Prisma 应用程序中加载环境变量，您可以使用 prisma.config.ts 文件以及 prisma/config 中的 env 助手。这种方法提供了更好的类型安全和配置管理。

安装 dotenv 包
```
npm install dotenv
```
在您的项目根目录中创建 .env 文件（如果不存在）并添加您的数据库连接字符串
```
DATABASE_URL="your_database_connection_string_here"
```

确保您的 prisma.config.ts 文件顶部导入了 dotenv/config

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from "prisma/config";

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: {
    path: 'prisma/migrations',
    seed: 'tsx prisma/seed.ts',
  },
  datasource: {
    url: env("DATABASE_URL"),
  },
});

概述​

配置接口​

支持的文件扩展名​

选项参考​

schema​

tables.external 和 enums.external​

migrations.path​

migrations.seed​

migrations.initShadowDb​

views.path​

typedSql.path​

experimental​

datasource.url​

datasource.shadowDatabaseUrl​

datasource.directUrl (已移除)​

adapter (已移除)​

engine (已移除)​

studio (已移除)​

studio.adapter (已移除)​

常见模式​

设置您的项目​

使用环境变量​

使用 dotenv（推荐用于 Prisma ORM v7）​

使用 Node.js v20+ 或 tsx 结合 --env-file 标志​

使用 Bun​

类型安全的环境变量​

处理可选环境变量​

使用多文件 schema​

路径解析​

与 pnpm prisma 的行为​

与 npm exec prisma 或 bun prisma 的行为​

全局 Prisma 安装​

Monorepos​

自定义配置位置​

加载环境变量​

概述

配置接口

支持的文件扩展名

选项参考

`schema`

`tables.external` 和 `enums.external`

`migrations.path`

`migrations.seed`

`migrations.initShadowDb`

`views.path`

`typedSql.path`

`experimental`

`datasource.url`

`datasource.shadowDatabaseUrl`

`datasource.directUrl` (已移除)

`adapter` (已移除)

`engine` (已移除)

`studio` (已移除)

`studio.adapter` (已移除)

常见模式

设置您的项目

使用环境变量

使用 dotenv（推荐用于 Prisma ORM v7）

使用 Node.js v20+ 或 tsx 结合 --env-file 标志

使用 Bun

类型安全的环境变量

处理可选环境变量

使用多文件 schema

路径解析

与 `pnpm prisma` 的行为

与 `npm exec prisma` 或 `bun prisma` 的行为

全局 Prisma 安装

Monorepos

自定义配置位置

加载环境变量