VillageSQL is a drop-in replacement for MySQL with extensions.
All examples on this page work on VillageSQL. Install Now →
mysql2 驱动将 Next.js App Router 应用程序连接到 MySQL,涵盖模式、迁移、从 Server Component 读取以及从 Server Action 写入。它假设已有一个用 create-next-app --src-dir 搭建好的应用,该命令会设置代码示例所使用的 @/* 导入别名。
安装 Drizzle 和 MySQL 驱动
Drizzle 需要mysql2 驱动来与 MySQL 通信,还需要 drizzle-kit 来生成和运行迁移:
drizzle-kit 迭代很快,并且在 dist-tags 下与 latest 并列发布了预发布标签(beta、rc)。安装前请检查 npm view drizzle-orm dist-tags 和 npm view drizzle-kit dist-tags,确认 latest 确实指向一个稳定版本而不是候选发布版本。
在 .env 中设置连接字符串:
创建数据库用户
创建一个专用数据库和一个限定在该数据库范围内的用户,而不是以root 身份连接应用程序:
'localhost' 主机进行匹配,无论存在哪些基于 IP 的授权;一个只以 'drizzle_app'@'127.0.0.1' 创建的用户无法通过套接字进行身份验证。到 127.0.0.1 的 TCP 连接通过反向 DNS 查找进行匹配,因此它是否同时满足 'localhost' 授权取决于服务器如何解析 127.0.0.1,而不是某条固定的 MySQL 规则。请授权给您的应用程序实际使用的主机,不要依赖 127.0.0.1 和 localhost 可以互换。
定义模式
Drizzle 的 MySQL 模式使用drizzle-orm/mysql-core 中的函数来描述每一列:
src/db/schema.ts
varchar 需要显式的 length。与 PostgreSQL 不同,MySQL 存储 VARCHAR 时最大长度是固化在列类型中的,因此 Drizzle 没有可以回退的默认值,需要预先提供该值。
配置 drizzle-kit
drizzle-kit 读取一个配置文件来了解模式在哪里以及如何连接数据库:
drizzle.config.ts
drizzle-kit 会在您的配置文件运行之前自己读取 .env,因此这里的 process.env.DATABASE_URL 已经被填充,不需要导入 dotenv。这是 drizzle-kit 特有的:普通的 Node 或 tsx 脚本没有内置这样的加载器,本指南后面的验证脚本会展示这一点。
把迁移脚本添加到 package.json:
package.json
生成并运行迁移
drizzle-kit generate 将模式文件与上一次生成的迁移进行比较,并写出一个新的 SQL 文件:
drizzle-kit 以绝对路径形式打印配置和模式路径;上面的 /path/to/your-app 代表您的项目目录。生成的文件名包含一个随机的两个单词后缀,因此您的文件名会不同;只有数字前缀(0000)对排序有意义。在模式没有变化的情况下重新运行 db:generate 会报告 No schema changes, nothing to migrate,而不是写出第二个文件。迁移本身是普通的 SQL:
drizzle/0000_premium_tiger_shark.sql
drizzle-kit migrate 第一次运行时会创建一个 __drizzle_migrations 表,用于跟踪哪些迁移文件已经应用过。确认两张表都存在:
创建数据库客户端
mysql2 驱动通过连接池进行连接,Drizzle 包装该连接池:
src/db/index.ts
mode: "default" 选项是 mysql2 驱动特有的,在 Drizzle 的 PostgreSQL 或 SQLite 驱动上没有对应项。省略它是类型错误,而不是静默的默认值。
在 Server Component 中读取文章
Server Component 可以在渲染期间直接调用db.select(),中间不需要 API 路由:
src/app/page.tsx
使用 Server Action 插入文章
Server Action 在服务器上运行,可以直接传给表单的action 属性:
src/app/actions.ts
revalidatePath("/") 也是必需的。没有它,Server Action 的响应不保证包含调用它的那个页面的刷新副本。
静态渲染陷阱
npm run build 编译应用程序,但它还会逐路由判断一个页面是可以在构建时预渲染一次,还是必须在每次请求时渲染。一个读取数据库而同一路由中没有其他动态 API(没有 cookies()、没有 headers()、没有 searchParams)的 Server Component,没有给 Next.js 任何强制按请求渲染的理由,因此它会在构建期间预渲染该页面一次,之后向每个访问者提供同一份 HTML。
这是可以复现的:从 page.tsx 中移除 export const dynamic = "force-dynamic"; 并重新构建,得到的路由被标记为静态:
npm run start 启动构建好的应用程序时并没有出现。页面一直提供构建时捕获的行数和内容。向 page.tsx 添加 export const dynamic = "force-dynamic"; 并重新构建后,路由变为动态:
export const dynamic = "force-dynamic";,或者另一个具有相同效果、强制按请求渲染的 Next.js API(比如读取 cookies())。
独立于 ORM 验证写入路径
一个通过 Drizzle 插入并且只检查 Drizzle 自身返回值的脚本并不能证明行已到达数据库;它只能证明驱动返回时没有抛出异常。请用一个单独的查询来验证:src/db/verify-insert.ts
tsx 运行它,它会直接执行 TypeScript:
import "dotenv/config" 在这里是必需的。Next.js 会自动为应用程序加载 .env,但用 tsx 运行的独立脚本是一个没有框架介入的普通 Node 进程,而 Node 本身不读取 .env 文件。
然后用一个从未经过应用程序的查询来确认该行存在:
常见问题
这在 VillageSQL 上的工作方式与在 MySQL 上相同吗?
相同。Drizzle 的 MySQL 方言和mysql2 驱动使用标准的 MySQL 线路协议,而 VillageSQL 是 MySQL 的直接替代品,具有相同的协议和客户端工具。上面的模式、迁移或查询代码中没有任何东西是特定于 MySQL 版本的。
我应该使用 drizzle-kit generate 加 migrate,还是 drizzle-kit push?
generate 加 migrate 会写出一个 SQL 迁移文件,您可以在它针对数据库运行之前审查并提交它,这正是本指南所用的方式。drizzle-kit push 把模式文件与实际数据库进行比较并直接应用差异,没有迁移文件。push 在早期原型阶段更快,但不会留下任何关于改了什么、何时改的记录,一旦其他开发者或环境依赖该模式,它就不能替代迁移文件。
为什么迁移文件夹里有一张叫 __drizzle_migrations 的表?
drizzle-kit migrate 在第一次运行时创建这张表,按哈希记录它已经应用过哪些迁移文件。migrate 正是靠它知道要跳过已经运行过的迁移,而不是再应用一次。
我可以直接从 Server Component 调用 db.insert(),而不用 Server Action 吗?
Server Component 只在渲染期间运行;没有来自浏览器的请求来响应用户操作触发写入。写入路径需要 Server Action、Route Handler,或者调用 API 路由的客户端代码。
故障排除
另请参阅
- Next.js 和 Prisma 搭配 MySQL — 同一个应用,用 Prisma 而不是 Drizzle 构建
- Next.js 搭配 MySQL — 完全不用 ORM 的连接设置、Server Actions 和 Route Handler 模式
- 在 ORM 中使用 MySQL:Django、Rails 和 Prisma — 在 Drizzle 之外的 ORM 中配置 MySQL 特定的设置
- MySQL 连接池 —
mysql2创建的连接池如何与 MySQL 的连接限制配合