prisma-database-setup

Prisma Database Setup 是 Prisma 官方插件（prisma/prisma-plugin）中的一项技能，用于指导开发者将 Prisma ORM 配置到不同的数据库提供商。

用途

当需要初始化新的 Prisma 项目、切换数据库提供商、配置连接字符串和环境变量、排查数据库连接问题、设置数据库特有功能，或生成并实例化 Prisma Client 时，可以引用该技能。

规则分类与优先级

技能按优先级组织规则，分为三类：

Provider Guides（提供商指南）——优先级 CRITICAL，前缀 provider names。
Prisma Postgres——优先级 HIGH，前缀 prisma-postgres。
Client Setup（客户端设置）——优先级 CRITICAL，前缀 prisma-client-setup。

系统前置条件

Node.js 20.19.0+
TypeScript 5.4.0+
Bun 运行时：如果使用 Bun，请用 bunx --bun prisma ... 运行 Prisma CLI 命令，以便 Prisma 使用 Bun 运行时而不是回退到 Node.js。

支持的数据库

数据库	Provider 字符串	说明
PostgreSQL	postgresql	默认，完整功能支持
MySQL	mysql	广泛支持，部分 JSON 差异
SQLite	sqlite	本地文件型，无 enum/标量列表
MongoDB	mongodb	Mongo 特有工作流；不要套用 SQL 驱动适配器指南
SQL Server	sqlserver	微软生态
CockroachDB	cockroachdb	分布式 SQL，兼容 Postgres
Prisma Postgres	postgresql	托管无服务器数据库

配置文件

配置形态取决于提供商和 Prisma 主版本：

所有提供商都使用 prisma/schema.prisma。
Prisma 7 的 SQL 配置通常使用 prisma.config.ts 存放数据源 URL。
MongoDB 项目应停留在 Prisma 6.x，在 schema 中保留 url = env("DATABASE_URL")，并继续使用经典 MongoDB 设置。

驱动适配器

标准 SQL 工作流使用驱动适配器。为数据库选择适配器和驱动，并将适配器传给 PrismaClient。

数据库	适配器	JS 驱动
PostgreSQL	@prisma/adapter-pg	pg
CockroachDB	@prisma/adapter-pg	pg
Prisma Postgres (Node.js)	@prisma/adapter-pg	pg
Prisma Postgres (edge/serverless)	@prisma/adapter-ppg	@prisma/ppg
MySQL / MariaDB	@prisma/adapter-mariadb	mariadb
SQLite	@prisma/adapter-better-sqlite3	better-sqlite3
SQLite (Turso/LibSQL)	@prisma/adapter-libsql	@libsql/client
SQL Server	@prisma/adapter-mssql	node-mssql

MongoDB 不应遵循 Prisma 7 的 SQL 适配器工作流。MongoDB 项目请使用最新的 Prisma 6.x 版本，并且不要为其安装 SQL 的 @prisma/adapter-* 包。

PostgreSQL 示例：

import 'dotenv/config'
import { PrismaClient } from '../generated/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

Prisma Client 设置（必需）

任何数据库都必须安装并生成 Prisma Client。

安装 Prisma CLI 和 Prisma Client：

npm install prisma --save-dev
npm install @prisma/client

添加 generator 块（prisma-client 需要显式 output 路径）：

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

生成 Prisma Client：

npx prisma generate

对于 SQL 提供商，使用数据库特定的驱动适配器实例化 Prisma Client：

import { PrismaClient } from '../generated/client'
import { PrismaPg } from '@prisma/adapter-pg'

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
const prisma = new PrismaClient({ adapter })

每次 schema 变更后都要重新运行 prisma generate。

快速参考

PostgreSQL：

datasource db {
  provider = "postgresql"
}

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

MySQL：

datasource db {
  provider = "mysql"
}

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

SQLite：

datasource db {
  provider = "sqlite"
}

generator client {
  provider = "prisma-client"
  output   = "../generated"
}

MongoDB：

datasource db {
  provider = "mongodb"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

对于 MongoDB，请停留在最新的 Prisma 6.x 系列，并将连接 URL 保留在 schema.prisma 中。不要将 MongoDB 项目迁移到 Prisma 7 的 SQL 适配器设置。

规则文件

详细设置说明见各规则文件：

references/postgresql.md
references/mysql.md
references/sqlite.md
references/mongodb.md
references/sqlserver.md
references/cockroachdb.md
references/prisma-postgres.md
references/prisma-client-setup.md

使用方式

为你的数据库选择对应的提供商参考文件，然后应用 references/prisma-client-setup.md 完成客户端生成和适配器设置。对于 MongoDB，请使用 references/mongodb.md，而不要照搬 SQL 适配器示例或 Prisma 7 配置模式。

适用场景与限制

该技能适用于 Prisma 项目的数据库配置、提供商切换、连接排错与客户端生成等场景。资料未提供收费、价格或效果方面的信息。MongoDB 与 SQL 提供商的工作流存在明确差异，需按资料说明分别处理。