跳转到主要内容

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
Drizzle ORM 是一个 TypeScript 查询构建器,它从模式文件生成 SQL 迁移,并为您提供带类型的查询 API,而没有自己的中间查询语言。本指南通过 Drizzle 和 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 身份连接应用程序:
通过 Unix 套接字的连接总是与 '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 路由的客户端代码。

故障排除

另请参阅