#oboard/morm

• 用尽量少的属性和 API 覆盖大部分常见场景
• 保持实现透明，允许随时绕过 ORM 手写 SQL
• 不使用运行时反射，不隐式修改用户语义

#Quick Start

1. 在你的应用 moon.mod.json 中添加依赖：

  "bin-deps": {
    "oboard/morm": "latest"
  },

2. 在你的 moon.pkg 添加

options(
  "pre-build": [
    {
      "command": "$mod_dir/.mooncakes/oboard/morm/morm-gen $input -o $output && moonfmt -w $output",
      "input": "entities.mbt",
      "output": "entities.g.mbt",
    },
    {
      "command": "$mod_dir/.mooncakes/oboard/morm/morm-gen $input -o $output && moonfmt -w $output",
      "input": "mapper.mbt",
      "output": "mapper.g.mbt",
    },
  ],
)

3. 在你的 entities.mbt 中定义实体：

• impl @morm.Entity 与 table() 元数据
• 各数据库方言下的建表 / 迁移 SQL
• 基于 #morm.query 的类型安全 Mapper 方法（含 save / delete）
• 统一返回 (String, FixedArray[@engine.Param]) 的参数化 SQL 构造器

• 类型驱动：字段的可空性由 T / T? 决定，而不是依赖大量注解
• 方言内建：支持 MySQL / PostgreSQL / Sqlite / SQLServer / Oracle 的建表和占位符差异
• SQL 优先：Query/Insert/Update/Delete/Upsert 只负责构造参数化 SQL，不绑定执行层
• 生成代码：所有内容都生成成普通 MoonBit 代码（见 example/*.g.mbt），可以直接查看和修改

• 统一建表与迁移 SQL 的生成
• 统一各数据库方言的语法差异
• 统一 SQL 参数绑定方式

#实体建模与可空性

///|
#morm.entity(name="teacher")
pub(all) struct Teacher {
  #morm.primary_key
  #morm.auto_increment
  #morm.bigint
  id : Int
  #morm.varchar(length="255")
  name : String
  #morm.varchar(length="255")
  major : String
  age : Int
  #morm.datetime
  birth_date : String?
} derive(ToJson, FromJson)

• 字段类型为 T（非 Option）时：列默认 NOT NULL
• 字段类型为 T?（Option[T]）时：列默认 NULLABLE
• 主键永远视为非空，即便你写成 id : Int?，也会被当成 NOT NULL 主键

#Attributes 使用指南

#代码生成：mormgen CLI

mormgen -i <input_file> -o <output_file>

# 生成实体的 table() 实现
mormgen example/entities.mbt -o example/entities.g.mbt

# 生成 mapper 实现
mormgen example/mapper.mbt -o example/mapper.g.mbt

#Mapper 与查询

#morm.mapper(entity="Student")
pub trait StudentMapper {
  #morm.query("SELECT * FROM students WHERE id = ?")
  pub fn find_student_by_id(Self, id : Int) -> Student?

  #morm.query("SELECT count(*) FROM students WHERE age = ?")
  pub fn count_students_by_age(Self, age : Int) -> Int?
}

• pub struct StudentMapperImpl { engine : &@engine.Engine }
• pub fn StudentMapperImpl::new(engine : &@engine.Engine) -> StudentMapperImpl
• 对应的 impl StudentMapper for StudentMapperImpl，内部用参数化 SQL 调用 engine.exec / engine.query
• 额外的通用方法：save 和 delete，直接基于实体的主键和唯一索引做 UPSERT / DELETE

///|
let engine = MySQLEngine::open("mysql://...")

///|
let mapper = StudentMapperImpl::new(engine)

///|
let stu = mapper.find_student_by_id(1)

///|
let n = mapper.count_students_by_age(18)

///|
let saved = mapper.save(stu)

///|
let deleted = mapper.delete(stu)

#SQL 构造器与渲染

• select_from(table)
• insert_into(table)
• update(table)
• delete_from(table)
• upsert_into(table)

let q = @morm.select_from("students")
  .where_eq("id", 1)
  .where_eq("name", "Alice")
  .order_by(Desc("id"))
  .offset(5)
  .limit(5)
let (sql, params) = @engine.render_default_sql(q.to_statement())

SELECT * FROM students WHERE id = ? AND name = ? ORDER BY id DESC LIMIT 5 OFFSET 5

• 在 PostgreSQL / Sqlite 下附带 RETURNING *，直接返回插入/更新后的行
• 在不支持 RETURNING 的方言（如 MySQL）下，save 会用主键或唯一索引回读一行，保证你最终拿到一条完整记录

#自动迁移（Auto-migrate）

let engine = MySQLEngine::open("mysql://root:123456@localhost:3306/test")
@morm.auto_migrate(engine, [Student::table()])
engine.close()

#运行测试与示例

# 运行全部测试
moon test