drizzle-seed 0.1.1 首发版使用指南为 Drizzle ORM 生成确定性测试数据的完整方案【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-ormdrizzle-seed是 Drizzle 团队官方发布的 TypeScript 数据填充seeding库目标是让你用一两行代码就能为 PostgreSQL、MySQL、SQLite 数据库批量生成真实感强且可复现的模拟数据。本文基于仓库中 drizzle-seed 0.1.1 首发版变更日志 展开结合drizzle-seed包的源码与测试完整讲解安装前提、seed函数的核心用法、count与seed两个关键选项以及库底层如何基于可播种的伪随机数生成器pRNG实现确定性数据生成。读完本文你将能够在自己的测试与开发环境中开箱即用地完成数据库造数与重置。版本背景与前置要求drizzle-seed0.1.1 是这一包在 Drizzle 生态中的 Initial Release首发版本。在使用前必须先满足一条硬性约束——变更日志中明确给出的 NOTEdrizzle-seed只能与drizzle-orm0.36.4或更高版本搭配使用。更低版本在运行时可能可以工作但会出现类型问题与自增主键identity column问题因为相关补丁是在drizzle-orm0.36.4中引入的。这一点在包配置中也有印证drizzle-seed/package.json 将drizzle-orm声明为 peer dependency 并限定0.36.4。因此正确的最小安装组合是npm install drizzle-orm npm install drizzle-seed安装后drizzle-seed通过exports字段同时提供 ESMindex.mjs与 CJSindex.cjs产物并带有完整的类型声明index.d.ts/index.d.mts/index.d.cjs见 drizzle-seed/package.json在主流打包器与 Node 环境中均可直接使用。基本用法10 条用户记录一键生成变更日志给出了一个最简示例创建 10 个带随机姓名和 id 的用户。完整代码如下与仓库 README 中的示例一致见 drizzle-seed/README.mdimport { pgTable, integer, text } from drizzle-orm/pg-core; import { drizzle } from drizzle-orm/node-postgres; import { seed } from drizzle-seed; const users pgTable(users, { id: integer().primaryKey(), name: text().notNull(), }); async function main() { const db drizzle(process.env.DATABASE_URL!); await seed(db, { users }); } main();这段代码的关键点在于表定义完全沿用 Drizzle ORM 的标准语法pgTable无需为 seeding 改写任何 schema 结构seed(db, { users })接收两个参数数据库实例db和包含了要填充的所有表的 schema 对象不传任何选项时库会为users表生成默认 10 行数据id由库自动生成合理的整数值name则从内置的名字数据集中随机生成。schema 对象既可以直接内联表定义如上面的{ users }也可以传入从一个 schema 文件整体导出的对象import * as schema from ./schema.ts; import { seed } from drizzle-seed; await seed(db, schema);这是官方推荐的组织方式尤其适合表数量较多的项目——库会自动遍历 schema 中的全部表并逐一填充。Optionscount与seedseed函数的第三个参数是一个选项对象变更日志重点介绍了其中的两个选项count和seed。count控制生成行数默认情况下seed会为每个表创建 10 条实体。当测试场景需要更多数据时通过选项对象指定即可await seed(db, schema, { count: 1000 });上面这行代码会为 schema 中的每个表各生成 1000 行数据。该默认值在源码中有直接体现SeedService 中定义了private defaultCountForTable 10;而当你在refine中对某个表单独指定count时又会以表级配置优先覆盖全局count见 SeedService.ts。seed控制数据确定性这是drizzle-seed最核心的选项。如果你希望后续每次运行都生成一组不同的值只需传入一个新的数字await seed(db, schema, { seed: 12345 });其背后的原理是库内置了一个可播种的伪随机数生成器pRNG只要seed数字相同、且 seeding 脚本没有改动每次生成的数据序列就完全一致换一个数字则得到一组全新的、不重复的数据。这一设计让“确定性”和“多样性”同时成立一致性Consistency测试每次运行在完全相同的数据集上结果可对比、可断言可调试Debugging当某个 bug 依赖特定数据时用同一个 seed 就能稳定复现团队协作Collaboration团队成员共享同一个 seed 数字即可在各自环境得到相同的数据集。源码层面seed值被透传进SeedService.generatePossibleGenerators未指定时默认为0见 SeedService.ts随后作为随机数序列的初始化依据。该包依赖的 pRNG 实现来自pure-rand见 package.json这也是“确定性生成”这一承诺的底层保证。两个选项可以组合使用例如一次生成 10 万行固定序列的数据await seed(db, schema, { count: 100000, seed: 1 });选项的完整形态与version从 src/index.ts 中seed函数的签名可以看到选项对象实际支持三个字段count、seed与versionoptions?: { count?: number; seed?: number; version?: 2 | 1 | undefined }其中version用于选择生成器 API 的版本1或2不传时默认使用最新版本v2这一默认逻辑定义在 SeedService.ts 与 apiVersion.ts 中若传入的版本号超出[1, latestVersion]范围会直接抛出错误SeedService.ts。用refine定制列级生成规则seed返回的并非普通 Promise而是一个实现了then/catch/finally且带有refine方法的SeedPromise类对象见 src/index.ts。refine让你针对某个表、某个列指定专门的生成器这是从“随机填充”走向“业务化造数”的关键能力。以下示例来自 src/index.ts 的 JSDocawait seed(db, schema, { count: 1000 }).refine((funcs) ({ users: { columns: { name: funcs.firstName({ isUnique: true }), email: funcs.email(), phone: funcs.phoneNumber({ template: 380 99 ###-##-## }), password: funcs.string({ isUnique: true }), }, count: 100000, }, posts: { columns: { title: funcs.valuesFromArray({ values: [Title1, Title2, Title3, Title4, Title5], }), content: funcs.loremIpsum({ sentencesCount: 3 }), }, }, }));这里体现了几类典型的生成器用法firstName({ isUnique: true })从名字数据集生成不重复的名字库内为每个生成器提供了对应的 Unique 版本见 Generators.ts 的replaceIfUnique逻辑phoneNumber({ template })按#占位符模板生成电话号码valuesFromArray从给定数组中取值支持传入带权重的分组数组实现按比例分布权重示例见 GeneratorFuncs.tsloremIpsum({ sentencesCount })生成指定句数的段落文本。除此之外GeneratorFuncs.ts 还内置了intPrimaryKey从 1 开始的顺序整数、number指定 min/max/precision 的浮点数、date/time/timestamp、boolean、json、array、email、city、country、state、streetAddress、companyName、jobTitle、uuid、default固定值等 30 余种生成器覆盖了绝大多数常见列类型的造数需求对应数据来源则分布在 datasets 目录 下例如firstNames.ts、countries.ts、emailDomains.ts、loremIpsumSentences.ts等。生成器基类AbstractGenerator定义了init/generate/updateParams等生命周期方法Generators.tsrefine返回的对象会被转换为RefinementsType后进入SeedService的生成流水线SeedService.ts。关系表与外键的处理drizzle-seed并不是简单地逐表独立填充——从 SeedService.ts 可以看出库会先从传入 schema 的关系包括外键约束和 Drizzlerelations定义中提取表间依赖再按依赖顺序排序先填充被引用的父表、后填充带外键的子表从而保证外键引用的完整性。对于循环依赖如 A 引用 B、B 又引用 A 的情况库也做了专门处理在 src/index.ts 中通过 DFS 检测环将循环关系标记为isCyclic随后在生成时先插入一侧、再回填另一侧的引用updateDataInDb阶段见 src/index.ts。这意味着自引用表、多对多桥接表这类容易“卡死”的造数场景drizzle-seed都能自动完成。用reset清空并重填数据库在测试套件中常见的需求是先清空旧数据、再灌入新的固定数据。drizzle-seed为此提供了reset函数其签名与行为在 src/index.ts 中有完整注释import * as schema from ./schema.ts; import { reset } from drizzle-seed; async function main() { const db drizzle(process.env.DATABASE_URL!); await reset(db, schema); } main();reset会按数据库方言执行不同的清空策略见 src/index.ts数据库底层 SQL 策略PostgreSQLtruncate schema.table1,schema.table2,... cascade;一次性级联截断resetPostgresMySQL先SET FOREIGN_KEY_CHECKS 0;逐表truncate最后恢复SET FOREIGN_KEY_CHECKS 1;resetMySqlSQLite先PRAGMA foreign_keys OFF;逐表delete from ...再恢复PRAGMA foreign_keys ON;借助resetseed的组合你可以轻松实现“每次测试前重置数据库并用固定 seed 重新造数”的标准流程保证每个用例都在干净、可预期的数据环境下运行。支持范围与底层执行细节支持的数据库从 src/index.ts 的seedFunc分支可以看出drizzle-seed目前支持 PostgreSQLPgDatabase、MySQLMySqlDatabase与 SQLiteBaseSQLiteDatabase三类数据库实例其他类型会抛出明确错误The drizzle-seed package currently supports only PostgreSQL, MySQL, and SQLite databases.。三种方言的完整填充流程分别由seedPostgres、seedMySql、seedSqlite实现并通过drizzle-kit生成对应的测试表结构见 package.json 的generate-for-tests:*脚本。批量插入的方言差异为保证大量插入时的性能库针对各数据库的参数占位符上限做了适配SeedService.ts 中定义了PostgreSQL单条语句最多 65535 个参数pglite 环境为 32740MySQL最多 100000 个参数注释中说明 MySQL 无硬性上限可按需调大SQLite最多 32766 个参数对应SQLITE_MAX_VARIABLE_NUMBER的默认值。超过上限时库会分批执行插入这也是它能稳定支撑count: 100000这类大规模造数的原因之一。验证与测试包内提供了覆盖三种方言的完整测试例如 tests/pg/pg.test.ts 及allDataTypesTest、cyclicTables、generatorsTest、softRelationsTest等子目录同时包含 MySQL、SQLite 对应的测试套件tests/mysql、tests/sqlite和 type-tests用于验证生成结果的正确性、唯一性约束与类型层面的完备性。总结drizzle-seed0.1.1 的首发版提供了一条从安装到落地的完整造数路径前置条件drizzle-orm 0.36.4开箱即用seed(db, schema)默认每个表生成 10 行数据两个核心选项count控制数量seed控制数据序列的确定性两者可自由组合进阶定制refine 30 余种生成器可精确控制每个列的取值规则与分布关系与循环依赖按外键依赖顺序填充自动处理循环引用配套重置reset按各数据库方言安全清空数据适合与seed组合用于测试套件。无论你是要写单元/集成测试、做开发环境演示数据还是搭建 CI 中可复现的数据基线drizzle-seed都能让你用最少的样板代码得到既真实又稳定的数据库填充结果。完整的 API 参考与更多示例可继续查看仓库中的 drizzle-seed/README.md 与 drizzle-seed 源码。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考