后端【免费下载链接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.项目地址https://gitcode.com/gh_mirrors/mi/mikro-orm点击查看免费下载本篇指南聚焦 MikroORM 7.2 中所有内置 SQL 驱动的安装、初始化、Schema 管理与原生查询能力覆盖 QueryBuilder、事务、多对多中间表等高频场景并深入讲解 SQLite 扩展、Turso/libSQL 远程库、Cloudflare D1 等前沿用法及各数据库的已知限制。读完本文你将能基于当前仓库的驱动源码快速选型并搭建出可运行的 SQL 数据访问层。驱动包一览开箱即用的 SQL 数据库支持MikroORM 以mikro-orm/core为核心通过独立驱动包接入各类 SQL 数据库。每个驱动包都导出了自己的MikroORM、EntityManager、EntityRepository与defineConfig同时保持核心 API 一致。按数据库选择对应的驱动安装即可# for postgresql (works with cockroachdb too) npm install mikro-orm/postgresql # for pglite (embedded PostgreSQL in WASM) npm install mikro-orm/pglite # for mysql (works with mariadb too) npm install mikro-orm/mysql # for mariadb (works with mysql too) npm install mikro-orm/mariadb # for sqlite npm install mikro-orm/sqlite # for libsql/turso npm install mikro-orm/libsql # for sql.js (in-memory SQLite in WASM, works in the browser) npm install mikro-orm/sql-js # for mssql npm install mikro-orm/mssql # for oracle npm install mikro-orm/oracledb驱动包将mikro-orm/core作为 peer dependency多数包管理器会自动安装。如果还要使用mikro-orm/cli、mikro-orm/migrations、mikro-orm/seeder等附加包请显式安装mikro-orm/core确保所有包共享同一个实例npm install mikro-orm/core mikro-orm/postgresql mikro-orm/migrations mikro-orm/cli从仓库源码看每个驱动包都遵循同一套骨架驱动类继承AbstractSqlDriver并绑定各自的连接类与平台类。例如 PostgreSqlDriver 继承AbstractSqlDriverPostgreSqlConnection并装配PostgreSqlPlatform而 LibSqlDriver 则复用SqlitePlatform与LibSqlConnection这正是 libSQL 与 SQLite 语法兼容的底层原因。初始化 ORMMikroORM.init 与 defineConfig创建配置文件并调用MikroORM.init()即可完成引导。为了让QueryBuilder等驱动特有 API 可用应从驱动包而非mikro-orm/core导入MikroORMimport { MikroORM } from mikro-orm/postgresql; // or any other SQL driver package const orm await MikroORM.init({ entities: [Author, Book], dbName: my-db-name, });也可以使用defineConfig辅助函数获得类型安全的配置import { defineConfig } from mikro-orm/postgresql; export default defineConfig({ entities: [Author, Book], dbName: my-db-name, });要使用em.createQueryBuilder()等驱动特有方法请从驱动包导入MikroORM、EntityManager或EntityRepository而不是从mikro-orm/core导入。从源码实现看驱动包的init本质上就是把驱动类注入配置后再交给核心引导。PostgreSqlMikroORM.ts 中的definePostgreSqlConfig展开后等价于defineConfig({ driver: PostgreSqlDriver, ...options })PostgreSqlMikroORM.init正是基于该配置调用super.initLibSqlMikroORM.ts 中的defineLibSqlConfig同理注入LibSqlDriver。因此驱动包导出defineConfig的语义就是在核心配置基础上预设好 driver 字段。Schema 管理三件套MikroORM 提供三套互补的数据库 Schema 工具SchemaGenerator— 直接根据实体元数据创建、更新或删除 Schema适合原型开发与开发环境Migrations— 面向生产流程的版本化 Schema 变更配合mikro-orm/migrations使用EntityGenerator— 逆向分析已有数据库自动生成实体文件。三者组合可覆盖从实体到数据库与从数据库到实体两个方向的完整工作流。QueryBuilder元数据感知的流式 SQL 构建QueryBuilder提供流式、类型安全的 SQL 查询 API。它感知实体元数据能够自动处理 join、别名和列映射const qb em.createQueryBuilder(Author); qb.select(*) .where({ name: { $like: %test% } }) .orderBy({ name: asc }) .limit(10); const authors await qb.getResultList();也可用于更新与删除const qb em.createQueryBuilder(Author); await qb.update({ name: updated }).where({ id: 123 }).execute(); await em.createQueryBuilder(Author).delete().where({ id: 456 }).execute();更完整的 APIjoin、子查询、union、分页等参见 QueryBuilder 文档。需要留意的是驱动包中部分数据库还有专属的 QueryBuilder 增强例如 MsSqlQueryBuilder 针对 SQL Server 的方言差异做了专门适配。事务默认隐式需要时显式控制默认情况下em.flush()计算出的全部变更会在一个数据库事务中执行——常规操作无需手动管理事务。工作单元Unit of Work会在 flush 前根据配置决定是否开启隐式事务相关逻辑位于 UnitOfWork.ts 中对implicitTransactions配置的读取。需要显式控制时使用em.transactional()await em.transactional(async em { const author new Author(God, helloheaven.god); em.persist(author); // if an error occurs, all changes are rolled back });implicitTransactions的默认值并非写死而是由平台能力决定Configuration.ts 中this.#options.implicitTransactions ?? this.#platform.usesImplicitTransactions()即支持隐式事务的平台默认开启。这一细节在下一节 Cloudflare D1 场景中至关重要。ManyToMany 关系与中间表Pivot TableSQL 驱动使用中间表承载ManyToMany关系。MikroORM 会自动管理中间表只需在实体上声明关系即可ManyToMany(() BookTag) tags new CollectionBookTag(this);如需自定义中间表名称使用pivotTable选项ManyToMany({ entity: () BookTag, pivotTable: book2tag }) tags new CollectionBookTag(this);中间表的数据写入由专门的 persister 负责例如 PivotCollectionPersister.ts 内部就是通过驱动层的nativeDelete/nativeUpdateMany批量维护中间表行这说明中间表操作同样走原生 SQL 路径以保证效率。原生查询绕过 ORM 的四种姿势当需要绕过 ORM 执行原生 SQL 时有两条查询路径与三类原生方法// via QueryBuilder const qb em.createQueryBuilder(Author); qb.select(*).where({ id: { $in: [1, 2, 3] } }); const res await qb.execute(); // or raw SQL directly const result await em.execute(SELECT 1 1 as result);对于不需要变更追踪的批量操作使用原生方法// insert without creating an entity instance await em.insert(Author, { name: test, email: testexample.com }); // bulk update await em.nativeUpdate(Author, { active: false }, { active: true }); // bulk delete await em.nativeDelete(Author, { active: false });这些方法直接执行 SQL不会触发生命周期钩子。从源码看nativeUpdate与nativeDelete等方法的实现在 AbstractSqlDriver.ts 中如nativeUpdate位于 1429 行附近、nativeDelete位于 1751 行附近它们绕过实体工厂与工作单元直接拼装 SQL 交给连接层执行因此在追求吞吐的批量场景中开销更低。扩展 SQLite通过 pool.afterCreate 加载扩展SQLite 缺少部分默认功能如正则regexp可通过 sqlean 等扩展补充。在pool.afterCreate回调中加载扩展const orm await MikroORM.init({ // ... pool: { afterCreate: (conn: any, done: any) { conn.loadExtension(/path/to/sqlean); done(null, conn); }, }, });afterCreate会在每条底层连接建立后执行因此能保证连接池中的每条连接都加载了扩展。注意扩展加载是 SQLite 原生连接的能力仅对本地文件数据库有效。连接远程 Turso 数据库mikro-orm/libsqlmikro-orm/libsql驱动同时支持本地与远程库。连接远程 Turso 时使用password选项传入认证 tokenimport { defineConfig } from mikro-orm/libsql; export default defineConfig({ dbName: process.env.LIBSQL_URL, password: process.env.LIBSQL_AUTH_TOKEN, });需要嵌入副本 同步embedded replicas with sync时通过driverOptions配置import { defineConfig } from mikro-orm/libsql; export default defineConfig({ dbName: local.db, password: process.env.LIBSQL_AUTH_TOKEN, driverOptions: { syncUrl: process.env.LIBSQL_URL, syncPeriod: 0.5, // 500ms }, });从 LibSqlConnection.ts 的源码可以确认几个关键实现细节远程 URL 通过REMOTE_URL /^(https?|libsql):\/\//正则识别dbName使用options.url ?? this.config.get(dbName)解析authToken会回落到config.get(password)这正是远程地址放 dbName、token 放 password写法的来源当dbName是远程 URL 或配置了syncUrl时连接会被标记为recycleConnection连接回收后会通过replayConnectionSetup重放初始化 SQL以保持会话状态一致远程 libSQL 连接不支持ATTACH DATABASE源码中会直接抛出错误提示改用本地文件库。使用 Cloudflare D1实验性实验性D1 支持目前处于实验阶段存在显著限制请谨慎使用。Cloudflare D1 是 serverless SQLite 数据库。通过driverOptions传入 Kysely D1 dialect 即可让 MikroORM 跑在 D1 上import { MikroORM } from mikro-orm/sqlite; import { D1Dialect } from kysely-d1; export default { async fetch(request: Request, env: Env) { const orm await MikroORM.init({ entities: [...], // the dbName is not used when a dialect is provided, but its still required dbName: d1, driverOptions: new D1Dialect({ database: env.DB }), // required: D1 does not support explicit transactions implicitTransactions: false, }); // ... }, };如果需要在运行时延迟创建 dialect可以传工厂函数MikroORM.init({ entities: [...], dbName: d1, driverOptions: () new D1Dialect({ database: env.DB }), implicitTransactions: false, });D1 的限制与常规 SQLite 相比D1 存在显著限制不支持事务D1 不支持显式事务语句BEGIN TRANSACTION。必须设置implicitTransactions: false才能让em.flush()正常工作。这意味着变更不再原子应用——如果 flush 中途出错可能出现部分变更已持久化、部分未持久化的情况。该配置的生效逻辑可以在 EntityManager.ts 的 flush 路径553 行附近对implicitTransactions false的判断中得到印证em.transactional()将失效既然没有事务支持包裹在em.transactional()中的代码得不到任何原子性保证不支持查询流式化大结果集无法流式读取必须整体加载进内存ALTER TABLE能力有限不支持ALTER COLUMN与ADD CONSTRAINT会影响 Schema 迁移。D1 支持的 SQL 语句细节可查阅 Cloudflare 官方 D1 SQL 文档。MS SQL Server 限制UUID 值以大写形式返回不支持级联路径中的循环cycles in cascade pathsSchema diffing 能力有限无原生全文搜索fulltext search支持Upsert 支持有限仓库中 mssql 驱动包 的MsSqlSchemaGenerator、MsSqlSchemaHelper、MsSqlQueryBuilder等文件正是为绕开上述部分限制所做的方言级适配例如查询构建与 Schema 生成都由专属类接管。Oracle 限制不支持级联路径中的循环外键没有ON UPDATE子句Oracle 原生不支持不支持单条查询中包含多条语句WHERE子句不支持元组比较tuple comparison外键不会自动建索引自定义驱动接入未内置的数据库如果需要支持仓库未覆盖的数据库可以实现自己的驱动。完整方案参见自定义驱动文档。接入方式是在初始化时通过driver选项指定import { MyCustomDriver } from ./MyCustomDriver.ts; const orm await MikroORM.init({ entities: [Author, Book], dbName: my-db-name, driver: MyCustomDriver, });从现有驱动的源码模式看一个自定义驱动通常需要继承AbstractSqlDriverSQL 系或IDatabaseDriver非 SQL 系、提供连接类与平台类、必要时返回自定义 ORM 类如getORMClass()。这是 MikroORM 保持数据库无关设计的关键扩展点。小结MikroORM 7.2 的 SQL 生态覆盖了从传统关系库PostgreSQL/MySQL/MariaDB/SQL Server/Oracle到嵌入式与 serverlessSQLite、SQL.js、pglite、libSQL/Turso、Cloudflare D1的完整光谱。选型时建议结合本文中的限制清单追求事务与流式能力选 PostgreSQL/MySQL轻量本地开发选 SQLite边缘计算场景才考虑实验性的 D1并务必关闭implicitTransactions。所有驱动共享同一套MikroORM.initdefineConfig引导流程与QueryBuilder、原生查询 API切换数据库的成本主要在于方言与限制差异而非 API 重学。赞分享后端【免费下载链接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.项目地址https://gitcode.com/gh_mirrors/mi/mikro-orm点击查看免费下载相关推荐MikroORM 使用 SQL 数据库驱动指南MySQL、MariaDB、PostgreSQL 与 SQLite 集成实战MikroORM 使用 SQL 数据库驱动指南MySQL、MariaDB、PostgreSQL 与 SQLite 集成实战 本篇技术指南聚焦 MikroORM后端3步掌握崩坏星穹铁道自动化三月七小助手完整使用指南3步掌握崩坏星穹铁道自动化三月七小助手完整使用指南 还在为《崩坏星穹铁道》中重复的日常任务而烦恼吗三月七小助手March7thAssistant是一款后端MikroORM 配置指南从实体发现、驱动连接到缓存与环境变量的完整实战手册MikroORM 配置指南从实体发现、驱动连接到缓存与环境变量的完整实战手册 这篇技术指南以 MikroORM 官方 Configuration 文档 htt后端上一篇TDengine PI 数据接入连接配置与 Windows 集成认证完全指南下一篇10分钟搞定CodiMD批量管理API脚本实现文档高效迁移指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考