Prisma Config 參考

總覽

Prisma Config 檔案使用 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") 
  }
});

搭配 PrismaConfig 類型使用 TypeScript 的 satisfies 運算子

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 編譯器設定相容。

建議

對於小型 TypeScript 專案，請使用 prisma.config.ts。
對於具有多個配置檔案的大型 TypeScript 專案（遵循 .config 目錄提案），請使用 .config/prisma.ts。

選項參考

`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`

此選項允許您定義一個腳本，在執行遷移後或使用 npx prisma db seed 指令時由 Prisma 執行來填充資料。該字串應為可在終端機執行的指令，例如配合 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 在建立遷移之前，在**影子資料庫 (shadow database)** 上執行的 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 引數中使用連線池 (Connection Pooler) 的 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 起，驅動轉接器 (Driver Adapters) 的遷移會自動運作，不需要在 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`	`物件`	否	無

`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 檔案中的環境變數。具體做法取決於您的執行環境 (Runtime) 和 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 執行時，只有在**專案根目錄**（即 package.json 宣告 Prisma 的地方）執行指令，CLI 才能偵測到設定檔。

從專案根目錄執行的範例

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 安裝在**工作區根目錄 (workspace root)**，pnpm prisma 將能從子目錄偵測到設定檔。
如果 Prisma 安裝在**子套件 (subpackage)** 中（例如 ./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

自定義設定檔位置

載入環境變數