create-t3-app 中的 Prisma 集成指南：Schema 设计、Prisma Client 与数据库填充实战

create-t3-app 中的 Prisma 集成指南Schema 设计、Prisma Client 与数据库填充实战【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-appPrisma 是 create-t3-app 默认推荐的 TypeScript ORM用于在 T3 Stack 中定义数据库 Schema、生成类型安全的客户端并在后端安全地访问数据。本指南将围绕 T3 脚手架中 Prisma 的完整落地方式展开从 Prisma Client 的全局单例实例化、schema.prisma的模型定义到切换 PostgreSQL/MySQL/PlanetScale 等数据库提供方再到通过prisma db seed快速填充测试数据帮助你在一套类型安全的全栈 Next.js 应用中把数据库层真正用起来。Prisma 在 create-t3-app 中的角色Prisma 是一个面向 TypeScript 的 ORM它允许你在一个schema.prisma文件中定义数据库 Schema 与模型然后生成一个类型安全的客户端供后端代码直接调用以操作数据库。这是 create-t3-app 在脚手架阶段集成的核心数据访问方案之一当你在交互式 CLI 中选择 Prisma 作为数据库工具时安装器会自动完成依赖安装、Schema 生成与客户端代码落地。从安装器的实现cli/src/installers/prisma.ts可以看出脚手架会做以下事情将prisma作为开发依赖devDependencies、prisma/client作为生产依赖加入package.json生成prisma/schema.prisma与src/server/db.ts即 Prisma Client 实例所在文件自动追加若干 npm scripts包括postinstall: prisma generate、db:push、db:studio、db:generate与db:migrate若选择 PlanetScale 作为数据库提供方还会额外安装prisma/adapter-planetscale与planetscale/database。依赖版本由仓库中的 cli/src/installers/dependencyVersionMap.ts 统一管理当前仓库锁定prisma/prisma/client/prisma/adapter-planetscale为^6.6.0planetscale/database为^1.19.0确保生成的项目拥有一组经过验证的兼容版本。Prisma Client全局单例与日志策略在脚手架生成的项目中Prisma Client 位于src/server/db.ts。它并非在每个路由文件中独立创建而是以全局变量的形式实例化一次并导出这正是 Prisma 官方针对 Next.js 开发模式推荐的最佳实践——避免热重载时反复创建客户端导致连接池耗尽。import { env } from ~/env; import { PrismaClient } from ../../generated/prisma; const createPrismaClient () new PrismaClient({ log: env.NODE_ENV development ? [query, error, warn] : [error], }); const globalForPrisma globalThis as unknown as { prisma: ReturnTypetypeof createPrismaClient | undefined; }; export const db globalForPrisma.prisma ?? createPrismaClient(); if (env.NODE_ENV ! production) globalForPrisma.prisma db;该实现对应模板 cli/template/extras/src/server/db/db-prisma.ts有三个值得注意的设计点日志分级开发环境下启用query、error、warn三种日志便于在终端观察 SQL 语句与告警生产环境只保留error避免刷屏与性能损耗。全局缓存非生产环境下将客户端实例挂到globalThis上Next.js 开发模式的模块热更新不会重建连接。客户端生成位置PrismaClient从../../generated/prisma导入说明generator client的output被指向了prisma/generated见下文 Schema 分析这是本仓库模板与 Prisma 默认node_modules输出位置不同的一点。如果选择 PlanetScale则生成 cli/template/extras/src/server/db/db-prisma-planetscale.ts 中的版本——它在创建客户端时通过new PrismaPlanetScale({ url: env.DATABASE_URL })传入数据库驱动适配器driver adapter这是 Planetscale 的 Serverless 数据库连接方式。在 tRPC 上下文中使用 db脚手架默认将 Prisma Client 注入到 tRPC 的 context 中。在 App Router 模式下生成的文件为 cli/template/extras/src/server/api/trpc-app/with-db.tsimport { db } from ~/server/db; export const createTRPCContext async (opts: { headers: Headers }) { return { db, ...opts, }; };这意味着在路由处理器中可以通过ctx.db直接访问数据库而无需在每个文件中单独import { db }。官方文档建议优先使用这种方式它让依赖注入更加清晰也便于在测试中替换 context。Pages Router 模式下的对应实现位于 cli/template/extras/src/server/api/trpc-pages/with-db.ts。Schema 文件模型定义与生成目标Prisma 的 Schema 位于生成项目的prisma/schema.prisma它是定义数据源datasource、生成器generator和业务模型model的唯一来源也是prisma generate、prisma migrate、prisma db push等命令的输入。以基础的 SQLite 模板cli/template/extras/prisma/schema/base.prisma为例generator client { provider prisma-client-js output ../generated/prisma } datasource db { provider sqlite url env(DATABASE_URL) } model Post { id Int id default(autoincrement()) name String createdAt DateTime default(now()) updatedAt DateTime updatedAt index([name]) }几个关键点generator client的output ../generated/prisma让生成的客户端落在prisma/generated/prisma与src/server/db.ts中的导入路径一一对应datasource db的url env(DATABASE_URL)从环境变量读取连接串绝不把凭据硬编码进 Schema脚手架自带的Post模型演示了自增主键、默认时间戳default(now())与自动更新时间戳updatedAt以及索引index([name])等常用写法你可以在此基础上扩充自己的业务模型。在脚手架生成的项目中DATABASE_URL等环境变量由 cli/template/base/src/env.js 中基于t3-oss/env-nextjs的createEnv做运行时校验应用启动前即会验证变量的存在与格式。结合 NextAuth.js 的 Schema当你在 CLI 中同时选择 NextAuth.js 与 Prisma 时安装器会选用 cli/template/extras/prisma/schema/with-auth.prisma 作为 Schema 模板。它按照 NextAuth.js 官方 Prisma 适配器的要求预置了四个模型的推荐字段Useridcuid 主键、name、email唯一、emailVerified、image以及指向Account、Session、Post的关系数组Accountprovider、providerAccountId、refresh_token、access_token、expires_at、token_type、scope、id_token、session_state等 OAuth 字段并通过unique([provider, providerAccountId])保证同一提供方下账号唯一userId关联到User且级联删除onDelete: CascadeSessionsessionToken唯一、expires同样关联User并级联删除VerificationTokenidentifier、token唯一、expires通过unique([identifier, token])组合唯一。同时Post模型被扩展为关联创建者model Post { ... createdBy User relation(fields: [createdById], references: [id]) createdById String ... }Schema 中的注释也提示当切换到 MySQL 或 SQL Server 时Account模型里refresh_token、access_token、id_token等字段需要取消// db.Text的注释以适配文本类型。安装器在数据库提供方为mysql/planetscale时会自动执行这一替换见 cli/src/installers/prisma.ts 第 57–59 行。默认数据库与切换数据源脚手架生成的默认数据库是 SQLite——它对开发环境和快速构建概念验证POC非常友好零外部依赖即可启动但官方明确不推荐用于生产环境。切换到其他数据库只需两步修改datasource的provider将sqlite改为postgresql或mysql更新环境变量DATABASE_URL把连接字符串指向你的真实数据库实例。安装器在生成时正是通过字符串替换完成 provider 切换的cli/src/installers/prisma.ts 第 46–56 行schemaText schemaText.replace( provider sqlite, provider ${ { mysql: mysql, postgres: postgresql, planetscale: mysql, }[databaseProvider] } );也就是说CLI 中选择mysql与planetscale都会在 Schema 中生成provider mysql区别在于 PlanetScale 版本cli/template/extras/prisma/schema/base-planetscale.prisma额外开启了previewFeatures [driverAdapters]、设置了relationMode prisma外键约束由应用层 Prisma 管理并在客户端使用prisma/adapter-planetscale驱动适配器连接。若你的 PlanetScale 数据库已开启外键约束可以移除该行注释说明。PostgreSQL 与 MySQL 切换时还有一个常见注意点Post模型使用Int自增主键生产环境大表更推荐 BigInt 或 cuid 字符串主键可根据实际需求调整。填充Seeding数据库快速灌入测试数据Seeding数据填充是快速为数据库写入测试数据的有效手段。create-t3-app 模板给出的完整方案如下。第一步创建prisma/seed.ts在生成项目的prisma/目录下创建seed.ts编写填充逻辑。模板推荐使用upsert存在则更新、不存在则创建保证脚本可重复执行import { db } from ../src/server/db/client; async function main() { const id cl9ebqhxk00003b600tymydho; await db.example.upsert({ where: { id, }, create: { id, }, update: {}, }); } main() .then(async () { await db.$disconnect(); }) .catch(async (e) { console.error(e); await db.$disconnect(); process.exit(1); });注意脚本在main()成功与失败两条路径上都调用了db.$disconnect()显式关闭数据库连接避免进程悬挂失败时以非零退出码结束方便 CI 检测。第二步在package.json中配置 seed 命令需要为 Prisma 提供 seed 命令入口和 TypeScript 运行器{ scripts: { db-seed: NODE_ENVdevelopment prisma db seed }, prisma: { seed: tsx prisma/seed.ts } }这里推荐使用 tsx 作为 TypeScript 运行器——它是基于 esbuild 的极速 TS 执行器无需任何 ESM 配置ts-node或其他运行器同样可以工作。第三步执行填充pnpm db-seed # 或 npm db-seed / yarn db-seedprisma db seed会根据package.json中prisma.seed配置找到并执行 seed 脚本。结合安装器自动生成的db:pushprisma db push、db:generateprisma migrate dev与db:migrateprisma migrate deploy脚本你可以在开发流程中快速完成「改 Schema → 同步数据库 → 填充数据 → 启动应用」的闭环。与 Drizzle 的对照可选create-t3-app 同时提供 Drizzle 作为 Prisma 之外的 ORM 选项。二者在脚手架中的差异主要体现在模板组织上Prisma 的 Schema 与 seed 位于prisma/目录客户端由prisma generate产出到prisma/generated而 Drizzle 则通过drizzle-kit管理迁移、Schema 定义在src/server/db/schema.ts参考 cli/template/extras/config/drizzle-config-sqlite.ts 中的schema与dialect配置。选择哪一个取决于团队对迁移工具、类型体验与生态的偏好本指南聚焦的 Prisma 方案更强调 Schema 驱动与官方工具链的一体化。小结在 create-t3-app 生成的 T3 Stack 应用中Prisma 已经完成了从依赖安装、Schema 生成到 tRPC 上下文注入的全链路配置src/server/db.ts以全局单例方式导出类型安全的db客户端并内置开发/生产差异化日志prisma/schema.prisma是数据库的单一事实来源NextAuth.js 场景下四个认证模型开箱即用默认 SQLite 适合快速起步修改provider与DATABASE_URL即可切换到 PostgreSQL、MySQL 或 PlanetScaleprisma/seed.tsprisma db seed提供可重复执行的测试数据填充方案。你可以基于脚手架生成的Post模型与db客户端在src/server/api/routers中直接编写自己的 CRUD 路由享受从数据库到前端 API 的全链路类型安全。【免费下载链接】create-t3-appThe best way to start a full-stack, typesafe Next.js app项目地址: https://gitcode.com/gh_mirrors/cr/create-t3-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考