VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
创建数据库
Prisma 需要两个数据库:一个供您的应用使用,另一个是它内部用来计算迁移的”影子”数据库。创建这两个数据库,以及一个对两者都有权限的专用用户:*.* 上授予更宽泛的 CREATE/DROP 权限让 Prisma 自己创建影子数据库,这样可以把密码泄露的影响范围限制在两个数据库,而不是整台服务器。
搭建应用
prisma 的 latest 标签指向一个 8.0 候选发布版本:可以试用,但对于一份要持续可用的指南来说是错误的默认值。
初始化 Prisma
prisma init 默认会运行一个 postinstall 步骤,把 Claude Code、Cursor 和 Windsurf 的代理技能搭建到您的仓库中(.claude/、.windsurf/、.agents/,外加一个 skills-lock.json)。--no-skills 跳过这一步。如果您在使用 Prisma 的同时也使用 AI 编码代理,这是一个确实有用的功能,只是不在本指南的范围内。
这会创建 prisma/schema.prisma、一个 .env 文件和 prisma7.config.ts(在 Prisma 7 中配置文件名带有版本后缀)。设置连接字符串:
.env
schema.prisma 中。从 Prisma 7 开始,连接 URL(包括影子数据库 URL)放在 prisma7.config.ts 中,而不是模式文件中:
prisma7.config.ts
schema.prisma 保留 prisma init 创建的 generator 块,现在数据源上只声明 provider,不带连接 URL:
prisma/schema.prisma
运行迁移
prisma/migrations/<timestamp>_init/migration.sql,并替您调用 prisma generate。确认表已存在:
使用驱动适配器连接
Prisma 7 生成的客户端不再自行连接:不带参数的new PrismaClient() 现在无法通过类型检查。您需要传给它一个驱动适配器,每种数据库一个包:
@prisma/adapter-mariadb 是同时适用于 MariaDB 和 MySQL 的适配器:线路协议是共享的,所以它在 VillageSQL 上的工作方式与在原版 MySQL 上相同。设置一个单例,这样 Next.js 开发模式下的热重载就不会在每次保存文件时打开一个新的连接池:
src/lib/prisma.ts
新账户的首次连接
MySQL 8 和 VillageSQL 使用caching_sha2_password 插件创建账户。某个账户第一次进行身份验证时,客户端必须完成一次 RSA 密钥交换;之后服务器会缓存结果,后续连接走一条跳过该步骤的更快路径。@prisma/adapter-mariadb 拒绝在未加密的连接上进行这种交换,因此在一台从未验证过这个账户的服务器上,构建会失败:
active=0 idle=0 让它读起来像是服务器无法访问。底层驱动的错误更具体:
.env
asyncmy 记录的陷阱相同,而且它时有时无的原因也相同:一旦任何客户端(包括 mysql CLI)为该账户完成过一次完整的身份验证,缓存的结果就会掩盖这个问题,直到缓存被 FLUSH PRIVILEGES 或服务器重启清除。
生成的客户端的导入路径有两个怪癖。它没有 index.ts,因此您要导入 @/generated/prisma/client(文件),而不是 @/generated/prisma(目录)。而且该文件中的每个导出都标注了 @ts-nocheck,因为它是生成的代码,供您导入而不是阅读。
在 Server Component 中读写
src/app/page.tsx
prisma.post.findMany() 作为 Server Component 运行,因此列表渲染时数据已经在 HTML 中,没有客户端获取。表单提交到一个 Server Action("use server"),它通过同一个 Prisma 客户端写入,并调用 revalidatePath("/"),这样新文章无需客户端刷新就会显示出来。
此时运行 npm run build 实际上会查询数据库:因为首页没有使用动态 API,Next.js 会在构建时把它预渲染为静态内容,这意味着 findMany() 在构建期间运行,而不只是在请求时运行。如果您的数据库在 npm run build 期间不可达,构建就会在那里失败,因此这个应用的 CI 流水线在构建时就需要一个可达的数据库,而不只是在运行时。
常见问题
生产环境需要影子数据库吗?
不需要。prisma migrate dev 在您开发时用它来检测模式漂移。在生产环境中,使用 prisma migrate deploy,它应用现有的迁移文件,完全不触碰影子数据库。
为什么我的独立脚本报错 “Cannot read properties of undefined (reading ‘prepareCacheLength’)”?
在那个脚本的环境中process.env.DATABASE_URL 是 undefined。Next.js 会为 next dev 和 next build 自动加载 .env,但普通的 node 或 tsx 脚本不会。在脚本顶部添加 import "dotenv/config"。
我可以改用 @prisma/adapter-pg 的 MySQL 对应物吗?
没有 MySQL 专属的适配器名称。@prisma/adapter-mariadb 就是 Prisma 为 MariaDB 和 MySQL(包括 VillageSQL)提供的那一个。
故障排除
另请参阅
- Next.js 和 Drizzle 搭配 MySQL — 同一个应用,用更轻量、SQL 优先的 ORM 而不是 Prisma 构建
- Next.js 搭配 MySQL — 完全不用 ORM 的连接设置、Server Actions 和 Route Handler 模式
- 在 ORM 中使用 MySQL — 对每个 ORM 都重要的设置,不只是 Prisma
- 连接池 — 驱动适配器的连接池大小如何与您的进程数相互作用