drizzle-orm 0.30.6 新特性PGlite 驱动——在浏览器与 Node.js 中运行 Postgres 数据库【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm导读drizzle-orm 0.30.6 正式引入了PGlite 驱动通过 drizzle-orm/src/pglite 模块你可以在浏览器、Node.js 和 Bun 中直接运行一个真实的 Postgres 数据库无需安装任何本地数据库服务。本文以该版本的变更日志为骨架结合 驱动源码 与 集成测试系统讲解 PGlite 的原理、五种drizzle()初始化方式、持久化方案、迁移与事务能力以及当前已知的两项限制帮助你快速上手这一零依赖的嵌入式 Postgres 方案。一、什么是 PGliteWASM 构建的 PostgresPGlite 是由 ElectricSQL 团队维护的一个 TypeScript 客户端库它将Postgres 编译为 WebAssemblyWASM打包发布。与以往依赖 Linux 虚拟机来模拟 Postgres 的浏览器内数据库方案不同PGlite 没有使用任何虚拟机——它就是直接在 WASM 中运行的 Postgres 本身整个包体积仅约2.6 MBgzipped。这意味着你可以在任意支持 WASM 的 JavaScript 运行时中获得一个具备完整 Postgres 语义的数据库实例它可以作为临时内存数据库进程结束后数据即消失适合单元测试、演示与原型开发持久化数据库在 Node.js / Bun 中写入文件系统在浏览器中写入 indexedDB实现跨会话的数据保留。在 drizzle-orm 中PGlite 被设计为一等公民驱动仓库的 package.json 中声明了对electric-sql/pglite的 peer 依赖要求0.2.0并在开发依赖中锁定^0.2.12用于测试验证。二、快速上手内存数据库的最小示例变更日志给出了最简用法。安装依赖后创建一个内存 PGlite 实例并交给drizzle()即可import { PGlite } from electric-sql/pglite; import { drizzle } from drizzle-orm/pglite; // 内存中的 Postgres const client new PGlite(); const db drizzle(client); await db.select().from(users);第一行导入 PGlite 本体第二行导入 drizzle-orm 的 PGlite 驱动入口。drizzle()返回的PgliteDatabase继承自PgDatabase见 driver.ts因此你之前掌握的Postgres 方言的查询构建器、关系查询、SQL 模板函数等全部 API 原样可用——PGlite 驱动的接入不需要改变任何业务查询代码。三、五种初始化方式drizzle() 的完整调用形态从 driver.ts 的导出函数签名 以及 module 驱动的初始化测试 可以看到drizzle()支持五种等价写法覆盖从完全托管到传入既有实例的所有场景1. 零参数——自动创建内存实例const db drizzle();当第一个参数为undefined或字符串时驱动内部会执行new PGlite(params[0])见 driver.ts因此零参数等价于传入内存数据库。2. 传入连接字符串const db drizzle(memory://);PGlite 的 URI 风格连接串同样被支持memory://表示内存模式。3. 传入已创建的 PGlite 客户端const client new PGlite(memory://); const db drizzle(client);4. 传入客户端 Drizzle 配置const db drizzle(client, { schema });第二个参数是标准的DrizzleConfig支持schema、logger、casing、cache等选项。传入schema后db.query.User这类关系查询 API即可用测试中通过expect(db.query.User).not.toStrictEqual(undefined)验证见 pglite.test.mjs。5. 使用对象形式统一配置推荐const db drizzle({ connection: { dataDir: ./data }, // 持久化目录 schema, }); // 或直接传入客户端 const db drizzle({ client, schema });对象形式支持connection与client两个分支传client时直接复用实例传connection时驱动会解构出dataDir作为持久化目录、其余字段作为PGliteOptions传入构造函数见 driver.ts。注意connection为对象时不能与client同时使用二者互斥。另外drizzle.mock()可用于纯类型/单元测试场景此时$client不可用返回类型上被标注为$client is not available on drizzle.mock()见 driver.ts。四、持久化从内存到文件系统与 indexedDB变更日志明确指出 PGlite 支持两种持久化路径Node.js / Bun通过dataDir参数把数据写入文件系统浏览器底层使用 indexedDB 存储刷新页面后数据仍然保留。在 drizzle-orm 的驱动封装中持久化目录通过connection.dataDir透传import { drizzle } from drizzle-orm/pglite; const db drizzle({ connection: { dataDir: ./data/pg, // 数据持久化到本地目录 }, });从源码看connection的类型是(PGliteOptions { dataDir?: string }) | string见 driver.ts即 PGlite 的全部原生选项如relaxedDurability等都可直接传入。集成测试中则采用new PGlite()的零参数内存模式并在每个测试用例前重建publicschema 以保证隔离见 pglite.test.ts。五、迁移支持migrate() 与标准迁移流程PGlite 驱动完整支持 drizzle-kit 生成的迁移文件。入口位于 drizzle-orm/src/pglite/migrator.ts用法与其他 Postgres 驱动完全一致import { PGlite } from electric-sql/pglite; import { drizzle } from drizzle-orm/pglite; import { migrate } from drizzle-orm/pglite/migrator; const client new PGlite(); const db drizzle(client); await migrate(db, { migrationsFolder: ./drizzle2/pg });migrate()内部调用readMigrationFiles读取迁移 SQL 文件再通过db.dialect.migrate()逐条执行并在默认 schema 下维护__drizzle_migrations迁移记录表。集成测试 pglite.test.ts 的迁移用例 验证了执行迁移 → 插入数据 → 查询回读的完整闭环包括迁移前后对相关表与迁移记录表的清理。六、事务与预编译查询会话层的实现细节驱动底层由 drizzle-orm/src/pglite/session.ts 承载包含三个核心类PgliteSession继承自PgSession其transaction()方法调用 PGlite 原生的client.transaction()并把事务会话包装为PgliteTransaction见 session.tsPgliteTransaction支持嵌套事务通过savepoint sp{n}/release savepoint/rollback to savepoint实现子事务回滚见 session.tsPglitePreparedQuery执行时通过fillPlaceholders填充占位符并借助 PGlite 的query()与rowMode选项区分数组行与对象行两种返回模式。值得注意的一个实现细节是PglitePreparedQuery针对 PGlite 的类型解析器做了定制为timestamp、timestamptz、interval、date以及它们对应的数组类型OID 1231/1115/1185/1187/1182注册了原样返回的自定义 parser见 session.ts从而保证这些时序/日期类型在结果映射中的行为与node-postgres保持一致避免 WASM 环境下的隐式类型转换偏差。此外会话层还挂接了 drizzle-orm 的缓存机制cache选项与$cache属性见 driver.ts与 pg-common-cache 测试 中验证的缓存场景一一对应。七、已知限制PGlite 侧待修复的两个问题变更日志如实列出了当前版本的两个限制它们源自 PGlite 本体而非 drizzle-orm 驱动层需要等待electric-sql/pglite上游修复刷新物化视图REFRESH MATERIALIZED VIEW会抛错执行SET TIME ZONE会抛错。由于这两点属于 PGlite 底层 WASM 构建的固有限制使用时建议需要物化视图刷新或时区切换场景的项目仍以原生 Postgres如node-postgres、postgres.js驱动为主将 PGlite 用于测试、原型、演示、离线/边缘计算等不需要这些能力的场景。drizzle-orm 的集成测试也对涉及物化视图、时区相关的 date/time 用例做了显式跳过标记注释标明not working in 0.2.12见 pglite.test.ts佐证了这两个限制在实测中的影响范围。八、实践建议与版本前提安装drizzle-orm需0.30.6本特性引入版本同时安装electric-sql/pglitepeer 依赖要求0.2.0仓库开发环境使用^0.2.12见 drizzle-orm/package.json。测试首选在 Vitest 等测试框架中PGlite 内存实例可以替代需要 Docker 或本机服务的集成测试数据库显著降低 CI 环境搭建成本pglite.test.ts 本身就是一个完整的参考范例覆盖了迁移、db.execute、RETURNING、查询构建器、缓存等多个维度。浏览器端由于存储走 indexedDBPGlite 非常适合离线优先的 Web 应用配合 drizzle-orm 的关系查询 API 可以在纯前端实现完整的数据库层。关注上游文末的两项限制分别对应 PGlite 的物化视图刷新与SET TIME ZONE问题升级electric-sql/pglite时可留意这两个 issue 的修复状态对应变更日志中列出的 electric-sql/pglite#63 与 #62。总的来说drizzle-orm 0.30.6 的 PGlite 驱动把嵌入式 Postgres的体验与完整的 drizzle-orm 查询能力打通——同一套PgDatabase抽象、同一套迁移流程、同一套事务语义既可以在 Node/Bun 中作为轻量数据库运行也可以下沉到浏览器端是测试与边缘场景下替换外部 Postgres 服务的高性价比方案。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 drizzle-orm 0.30.6 新特性：PGlite 驱动——在浏览器与 Node.js 中运行 Postgres 数据库
drizzle-orm 0.30.6 新特性PGlite 驱动——在浏览器与 Node.js 中运行 Postgres 数据库【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm导读drizzle-orm 0.30.6 正式引入了PGlite 驱动通过 drizzle-orm/src/pglite 模块你可以在浏览器、Node.js 和 Bun 中直接运行一个真实的 Postgres 数据库无需安装任何本地数据库服务。本文以该版本的变更日志为骨架结合 驱动源码 与 集成测试系统讲解 PGlite 的原理、五种drizzle()初始化方式、持久化方案、迁移与事务能力以及当前已知的两项限制帮助你快速上手这一零依赖的嵌入式 Postgres 方案。一、什么是 PGliteWASM 构建的 PostgresPGlite 是由 ElectricSQL 团队维护的一个 TypeScript 客户端库它将Postgres 编译为 WebAssemblyWASM打包发布。与以往依赖 Linux 虚拟机来模拟 Postgres 的浏览器内数据库方案不同PGlite 没有使用任何虚拟机——它就是直接在 WASM 中运行的 Postgres 本身整个包体积仅约2.6 MBgzipped。这意味着你可以在任意支持 WASM 的 JavaScript 运行时中获得一个具备完整 Postgres 语义的数据库实例它可以作为临时内存数据库进程结束后数据即消失适合单元测试、演示与原型开发持久化数据库在 Node.js / Bun 中写入文件系统在浏览器中写入 indexedDB实现跨会话的数据保留。在 drizzle-orm 中PGlite 被设计为一等公民驱动仓库的 package.json 中声明了对electric-sql/pglite的 peer 依赖要求0.2.0并在开发依赖中锁定^0.2.12用于测试验证。二、快速上手内存数据库的最小示例变更日志给出了最简用法。安装依赖后创建一个内存 PGlite 实例并交给drizzle()即可import { PGlite } from electric-sql/pglite; import { drizzle } from drizzle-orm/pglite; // 内存中的 Postgres const client new PGlite(); const db drizzle(client); await db.select().from(users);第一行导入 PGlite 本体第二行导入 drizzle-orm 的 PGlite 驱动入口。drizzle()返回的PgliteDatabase继承自PgDatabase见 driver.ts因此你之前掌握的Postgres 方言的查询构建器、关系查询、SQL 模板函数等全部 API 原样可用——PGlite 驱动的接入不需要改变任何业务查询代码。三、五种初始化方式drizzle() 的完整调用形态从 driver.ts 的导出函数签名 以及 module 驱动的初始化测试 可以看到drizzle()支持五种等价写法覆盖从完全托管到传入既有实例的所有场景1. 零参数——自动创建内存实例const db drizzle();当第一个参数为undefined或字符串时驱动内部会执行new PGlite(params[0])见 driver.ts因此零参数等价于传入内存数据库。2. 传入连接字符串const db drizzle(memory://);PGlite 的 URI 风格连接串同样被支持memory://表示内存模式。3. 传入已创建的 PGlite 客户端const client new PGlite(memory://); const db drizzle(client);4. 传入客户端 Drizzle 配置const db drizzle(client, { schema });第二个参数是标准的DrizzleConfig支持schema、logger、casing、cache等选项。传入schema后db.query.User这类关系查询 API即可用测试中通过expect(db.query.User).not.toStrictEqual(undefined)验证见 pglite.test.mjs。5. 使用对象形式统一配置推荐const db drizzle({ connection: { dataDir: ./data }, // 持久化目录 schema, }); // 或直接传入客户端 const db drizzle({ client, schema });对象形式支持connection与client两个分支传client时直接复用实例传connection时驱动会解构出dataDir作为持久化目录、其余字段作为PGliteOptions传入构造函数见 driver.ts。注意connection为对象时不能与client同时使用二者互斥。另外drizzle.mock()可用于纯类型/单元测试场景此时$client不可用返回类型上被标注为$client is not available on drizzle.mock()见 driver.ts。四、持久化从内存到文件系统与 indexedDB变更日志明确指出 PGlite 支持两种持久化路径Node.js / Bun通过dataDir参数把数据写入文件系统浏览器底层使用 indexedDB 存储刷新页面后数据仍然保留。在 drizzle-orm 的驱动封装中持久化目录通过connection.dataDir透传import { drizzle } from drizzle-orm/pglite; const db drizzle({ connection: { dataDir: ./data/pg, // 数据持久化到本地目录 }, });从源码看connection的类型是(PGliteOptions { dataDir?: string }) | string见 driver.ts即 PGlite 的全部原生选项如relaxedDurability等都可直接传入。集成测试中则采用new PGlite()的零参数内存模式并在每个测试用例前重建publicschema 以保证隔离见 pglite.test.ts。五、迁移支持migrate() 与标准迁移流程PGlite 驱动完整支持 drizzle-kit 生成的迁移文件。入口位于 drizzle-orm/src/pglite/migrator.ts用法与其他 Postgres 驱动完全一致import { PGlite } from electric-sql/pglite; import { drizzle } from drizzle-orm/pglite; import { migrate } from drizzle-orm/pglite/migrator; const client new PGlite(); const db drizzle(client); await migrate(db, { migrationsFolder: ./drizzle2/pg });migrate()内部调用readMigrationFiles读取迁移 SQL 文件再通过db.dialect.migrate()逐条执行并在默认 schema 下维护__drizzle_migrations迁移记录表。集成测试 pglite.test.ts 的迁移用例 验证了执行迁移 → 插入数据 → 查询回读的完整闭环包括迁移前后对相关表与迁移记录表的清理。六、事务与预编译查询会话层的实现细节驱动底层由 drizzle-orm/src/pglite/session.ts 承载包含三个核心类PgliteSession继承自PgSession其transaction()方法调用 PGlite 原生的client.transaction()并把事务会话包装为PgliteTransaction见 session.tsPgliteTransaction支持嵌套事务通过savepoint sp{n}/release savepoint/rollback to savepoint实现子事务回滚见 session.tsPglitePreparedQuery执行时通过fillPlaceholders填充占位符并借助 PGlite 的query()与rowMode选项区分数组行与对象行两种返回模式。值得注意的一个实现细节是PglitePreparedQuery针对 PGlite 的类型解析器做了定制为timestamp、timestamptz、interval、date以及它们对应的数组类型OID 1231/1115/1185/1187/1182注册了原样返回的自定义 parser见 session.ts从而保证这些时序/日期类型在结果映射中的行为与node-postgres保持一致避免 WASM 环境下的隐式类型转换偏差。此外会话层还挂接了 drizzle-orm 的缓存机制cache选项与$cache属性见 driver.ts与 pg-common-cache 测试 中验证的缓存场景一一对应。七、已知限制PGlite 侧待修复的两个问题变更日志如实列出了当前版本的两个限制它们源自 PGlite 本体而非 drizzle-orm 驱动层需要等待electric-sql/pglite上游修复刷新物化视图REFRESH MATERIALIZED VIEW会抛错执行SET TIME ZONE会抛错。由于这两点属于 PGlite 底层 WASM 构建的固有限制使用时建议需要物化视图刷新或时区切换场景的项目仍以原生 Postgres如node-postgres、postgres.js驱动为主将 PGlite 用于测试、原型、演示、离线/边缘计算等不需要这些能力的场景。drizzle-orm 的集成测试也对涉及物化视图、时区相关的 date/time 用例做了显式跳过标记注释标明not working in 0.2.12见 pglite.test.ts佐证了这两个限制在实测中的影响范围。八、实践建议与版本前提安装drizzle-orm需0.30.6本特性引入版本同时安装electric-sql/pglitepeer 依赖要求0.2.0仓库开发环境使用^0.2.12见 drizzle-orm/package.json。测试首选在 Vitest 等测试框架中PGlite 内存实例可以替代需要 Docker 或本机服务的集成测试数据库显著降低 CI 环境搭建成本pglite.test.ts 本身就是一个完整的参考范例覆盖了迁移、db.execute、RETURNING、查询构建器、缓存等多个维度。浏览器端由于存储走 indexedDBPGlite 非常适合离线优先的 Web 应用配合 drizzle-orm 的关系查询 API 可以在纯前端实现完整的数据库层。关注上游文末的两项限制分别对应 PGlite 的物化视图刷新与SET TIME ZONE问题升级electric-sql/pglite时可留意这两个 issue 的修复状态对应变更日志中列出的 electric-sql/pglite#63 与 #62。总的来说drizzle-orm 0.30.6 的 PGlite 驱动把嵌入式 Postgres的体验与完整的 drizzle-orm 查询能力打通——同一套PgDatabase抽象、同一套迁移流程、同一套事务语义既可以在 Node/Bun 中作为轻量数据库运行也可以下沉到浏览器端是测试与边缘场景下替换外部 Postgres 服务的高性价比方案。【免费下载链接】drizzle-ormORM项目地址: https://gitcode.com/gh_mirrors/dr/drizzle-orm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考