后端【免费下载链接】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点击查看免费下载CockroachDB 是一款分布式 SQL 数据库其对外提供 PostgreSQL 线协议兼容接口。MikroORM 通过mikro-orm/postgresql驱动即可无缝接入 CockroachDB绝大多数 ORM 特性开箱即用仅需在连接配置、主键类型与清库方式上做针对性调整。读完本文你将掌握 MikroORM CockroachDB 的完整配置方法、UUID 与 BigInt 两种主键方案的选择依据以及 schema 生成、事务、批量写入等生产级特性的正确用法。为什么 CockroachDB 可以直接使用 PostgreSQL 驱动MikroORM 没有为 CockroachDB 单独发布驱动包而是明确推荐直接使用mikro-orm/postgresql。CockroachDB 与 PostgreSQL 在线协议wire protocol兼容绝大多数 SQL 语法与类型系统保持一致因此驱动层无需任何特殊适配。从源码结构看PostgreSqlConnection 基于pg驱动建立连接池并通过TypeOverrides注册类型解析器PostgreSqlPlatform 则负责数组、日期、interval 等 PostgreSQL 特有类型的值转换——这些能力对 CockroachDB 同样生效。安装只需要安装 PostgreSQL 驱动不需要任何额外的 CockroachDB 专属包npm install mikro-orm/core mikro-orm/postgresqlmikro-orm/core提供 ORM 核心EntityManager、Unit of Work、Identity Map、QueryBuilder 等mikro-orm/postgresql提供驱动与连接实现。如需使用迁移、种子、实体生成等能力可再按需安装mikro-orm/migrations、mikro-orm/seeder、mikro-orm/entity-generator仓库的 cockroachdb 兼容性测试 正是同时启用了这三个扩展。基础配置最小化的 CockroachDB 配置如下import { defineConfig } from mikro-orm/postgresql; export default defineConfig({ entities: [./dist/entities], entitiesTs: [./src/entities], dbName: my_database, host: localhost, port: 26257, user: root, password: , });需要注意CockroachDB 默认监听端口是26257而 PostgreSQL 是5432。配置中entities/entitiesTs分别指向编译产物与 TypeScript 源码中的实体目录用于元数据发现user在本地开发环境通常为root密码默认为空。CockroachDB CloudSSL 配置CockroachDB Cloud 强制要求 SSL 连接。此时需要通过driverOptions传入 CA 证书该选项会直接映射到pg.Pool的连接参数import { defineConfig } from mikro-orm/postgresql; import { readFileSync } from node:fs; export default defineConfig({ dbName: my_database, host: your-cluster.cockroachlabs.cloud, port: 26257, user: your-user, password: your-password, driverOptions: { ssl: { ca: readFileSync(./path/to/ca-cert.crt, utf8), }, }, });driverOptions是 MikroORM 向底层驱动透传配置的通用入口其内部类型即pg.PoolConfig见 PostgreSqlConnection.mapOptions它会将driverOptions与连接池的min/max/idleTimeoutMillis等参数合并后交给pg。除ssl.ca外你还可以在这里配置ssl.rejectUnauthorized等pg支持的选项。主键方案这是接入 CockroachDB 最关键的一步CockroachDB 的serial类型基于unique_rowid()生成 64 位整数与 PostgreSQL 的serialint4配合 sequence不同这些是int8值可能超出 JavaScript 的Number.MAX_SAFE_INTEGER9007199254740991。pg驱动会把超范围的大整数以字符串形式返回因此实体主键类型必须相应调整。方案一UUID 主键推荐CockroachDB 官方建议使用 UUID 作为主键以获得跨节点的均匀数据分布若使用serial/自增键容易在写入时产生热点。仓库的 兼容性测试 中所有实体也统一采用 UUID 主键并配合defaultRaw(gen_random_uuid())由数据库生成默认值。defineEntity 写法const Author defineEntity({ name: Author, properties: { id: p.uuid().primary(), name: p.string(), }, });装饰器写法Entity() class Author { PrimaryKey({ type: uuid }) id: string v4(); Property() name!: string; }v4()来自uuid包在应用侧生成 UUID也可以像测试实体那样省略赋值改用defaultRaw(gen_random_uuid())交给 CockroachDB 生成。方案二serial主键配合BigIntType如果希望保留自增风格的键必须使用BigIntType将serial的int8值映射为string或bigint绝不能是number。defineEntity 写法映射为stringconst Author defineEntity({ name: Author, properties: { id: p.bigint(string).primary(), name: p.string(), }, });或使用原生bigintconst Author defineEntity({ name: Author, properties: { id: p.bigint().primary(), name: p.string(), }, });装饰器写法映射为stringEntity() class Author { PrimaryKey({ type: new BigIntType(string) }) id!: string; }或使用原生bigintEntity() class Author { PrimaryKey() id!: bigint; }从 BigIntType 源码 可以看到它的三种模式默认bigint模式把数据库返回的字符串转成原生bigintstring模式保留字符串number模式则转成Number——因此对 CockroachDB 的int8主键number模式同样是危险的只有值确定不超范围时才可用。唯一不工作的写法PrimaryKey() id!: number/p.integer().primary()。CockroachDB 的serial值对 JavaScript 的number类型来说太大读取时会丢失精度。普通整数列CockroachDB 在内部把所有整数类型int2、int4、int8都映射为 64 位整数。pg驱动同样会把超出Number.MAX_SAFE_INTEGER的值以字符串返回。对age、count这类常见业务字段值通常落在安全范围内直接以number类型使用没有问题。仓库测试中甚至有这样的断言写入age: 42后读出Number(found.age)为 42见 cockroachdb.test.ts说明int4列在 CockroachDB 上读取后需要按字符串处理再转NumberMikroORM 的值转换流程能够正确处理。Schema Generator 的使用与注意事项Schema 生成器对 CockroachDB 完全可用orm.schema.create()、orm.schema.update()、orm.schema.drop()均可照常使用。仓库测试中通过getCreateSchemaSQL与getUpdateSchemaSQL验证了建表 SQL 能正常产出见 cockroachdb.test.ts。清库TRUNCATE ... RESTART IDENTITY不可用CockroachDB 不支持TRUNCATE ... RESTART IDENTITY。调用orm.schema.clear()时必须传入truncate: false让其回退到按依赖顺序生成的DELETE语句await orm.schema.clear({ truncate: false });从 SqlSchemaGenerator.clear 的实现可以印证clear()默认走TRUNCATE分支只有显式传入truncate: false时才回退到基类实现即按外键依赖顺序逐表执行有序DELETE。仓库测试的beforeEach也统一使用该写法见 cockroachdb.test.ts。Schema Diffing注意目录实现的差异由于 CockroachDB 的 catalog系统目录实现与 PostgreSQL 存在细微差别schema 内省可能报告一些与 PostgreSQL 相比的假差异。如果在orm.schema.getUpdateSchemaSQL()的输出中看到意外的 diff务必逐条人工审查后再应用避免误改表结构。已验证可用的功能清单以下功能经过 cockroachdb 兼容性测试 实际验证可在 CockroachDB 上放心使用CRUD 操作create、read、update、delete 全覆盖测试中分别验证了写入、读取、更新、删除与findOneOrFail关系映射ManyToOne、OneToMany、ManyToMany、OneToOne含pivotTable自定义中间表与mappedBy双向关系自引用关系如Author.favouriteAuthor指向自身的 ManyToOnePopulate 提示与加载策略SELECT_IN与JOINEDLoadStrategy.JOINED下批量预加载 author、publisher、tags 均通过断言QueryBuilder条件、排序、分页组合查询如where({ age: { $gte: 30 } }).orderBy({ name: asc })findAndCount分页limit/offset组合可用事务与回滚em.transactional()内提交与主动抛错回滚均验证通过批量插入单次 flush 插入多条记录Upsertem.upsert()按唯一键更新或插入JSONB 列嵌套对象整体读写数组列如text[]identities: [id1, id2, id3]UUID 主键与serial 主键配合BigIntType或bigintSchema 生成器create、update、drop迁移mikro-orm/migrations扩展已启用并可配合使用进阶能力复合主键基于两个 ManyToOne 主键、带version字段的乐观锁timestamptz版本列在更新后变化已知限制一览特性状态说明serial/bigserial主键需用BigIntType或 UUIDunique_rowid()返回int8number类型不可用整数类型内部统一映射为int8小值可作为number大值需bigint或stringTRUNCATE ... RESTART IDENTITY不支持改用orm.schema.clear({ truncate: false })polygon、line、path几何类型不支持CockroachDB 没有 PostgreSQL 的几何类型全文检索tsvector不支持CockroachDB 有自有的全文检索方案原生 PostgreSQL 枚举有限支持建议改用 check 约束物化视图不支持CockroachDB 不支持CREATE MATERIALIZED VIEW可延迟约束不支持CockroachDB 不支持INITIALLY DEFERRED从仓库的 deferrable-constraints 测试 与 materialized-views 文档 可以看出这些属于 PostgreSQL 的独有能力接入 CockroachDB 时需绕行枚举改用 check 约束、物化视图改用普通视图或应用层缓存。完整示例Author 与 Book 的一对多模型以下示例覆盖从初始化、建表、写入关系到带 populate 读取的完整流程同时给出 defineEntity 与装饰器两种实体定义风格。defineEntity 风格const Author defineEntity({ name: Author, properties: { id: p.uuid().primary(), name: p.string(), email: p.string(), books: () p.oneToMany(Book).mappedBy(author), }, }); const Book defineEntity({ name: Book, properties: { id: p.uuid().primary(), title: p.string(), author: () p.manyToOne(Author), }, }); const orm await MikroORM.init({ entities: [Author, Book], dbName: my_database, host: localhost, port: 26257, user: root, password: , }); await orm.schema.update(); const em orm.em.fork(); const author em.create(Author, { name: John, email: johnexample.com }); em.create(Book, { title: My Book, author }); await em.flush(); const books await em.find(Book, {}, { populate: [author] }); console.log(books[0].author.name); // John await orm.close();装饰器风格Entity() class Author { PrimaryKey({ type: uuid }) id: string v4(); Property() name!: string; Property() email!: string; OneToMany(() Book, book book.author) books new CollectionBook(this); } Entity() class Book { PrimaryKey({ type: uuid }) id: string v4(); Property() title!: string; ManyToOne(() Author) author!: Author; } const orm await MikroORM.init({ entities: [Author, Book], driver: PostgreSqlDriver, metadataProvider: ReflectMetadataProvider, dbName: my_database, host: localhost, port: 26257, user: root, password: , }); await orm.schema.update(); const em orm.em.fork(); const author em.create(Author, { name: John, email: johnexample.com }); em.create(Book, { title: My Book, author }); await em.flush(); const books await em.find(Book, {}, { populate: [author] }); console.log(books[0].author.name); // John await orm.close();注意装饰器风格下实体使用反射元数据时需要显式指定driver: PostgreSqlDriver与metadataProvider: ReflectMetadataProvider而 defineEntity 风格从mikro-orm/postgresql导入后无需额外声明。小结与进一步阅读接入 CockroachDB 时只需要记住三条核心规则端口用26257、主键用 UUID 或BigIntType绝不用number、清库时clear({ truncate: false })。其余能力——CRUD、四种关系、QueryBuilder、事务、批量写入、upsert、JSON/数组列、schema 生成与迁移——都与 PostgreSQL 用法一致。想要深入了解相关机制可以在当前仓库中继续阅读define-entity 指南defineEntity API 全解、decorators 指南装饰器实体定义、schema-generator 指南建表/变更/清库的完整语义、migrations 指南迁移工作流以及 cockroachdb 兼容性测试 这份可运行的集成测试它几乎是本文所有结论的活证据。赞分享后端【免费下载链接】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 与 CockroachDB 集成实战指南基于 PostgreSQL 驱动的配置、主键策略与兼容性边界MikroORM 与 CockroachDB 集成实战指南基于 PostgreSQL 驱动的配置、主键策略与兼容性边界 本文是 MikroORM 官方使用指南后端MikroORM 与 CockroachDB 集成指南配置、主键策略与兼容性要点MikroORM 与 CockroachDB 集成指南配置、主键策略与兼容性要点 MikroORM 通过 mikro orm/postgresql 驱动原生后端MikroORM 使用 SQL 数据库驱动指南MySQL、MariaDB、PostgreSQL 与 SQLite 集成实战MikroORM 使用 SQL 数据库驱动指南MySQL、MariaDB、PostgreSQL 与 SQLite 集成实战 本篇技术指南聚焦 MikroORM后端上一篇如何为wuhaicc/xlnet_base_cased贡献代码开发者参与指南和社区规范下一篇和弦转录革命MOSS-Music-8B-Instruct如何实现带时间戳的和弦分析与转录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考