#vellum

• 用 get、put、delete 读写数据。
• 一次事务可以修改多个键，最后统一 commit，或用 abort 撤销。
• 重新打开时自动恢复完整已提交的 WAL，并检查页结构。

#快速开始（0.4.1）

import {
  "Nanaloveyuki/vellum@0.4.1",
}

import {
  "Nanaloveyuki/vellum",
  "moonbitlang/async",
}
pkgtype(kind: "executable")

async fn main {
  let db = @vellum.open("notes.db")
  defer db.close()
  let txn = db.begin()
  txn.put(b"hello", b"vellum")
  txn.commit()
  db.close()

  let again = @vellum.open("notes.db")
  defer again.close()
  let read = again.begin()
  match read.get(b"hello") {
    Some(value) => println(value.to_string())
    None => println("missing")
  }
  read.abort()
}

#事务与错误处理

1. 关闭当前 Db，不要直接重试提交。
2. 重新打开同一路径，让数据库完成恢复；打开失败时处理该错误。
3. 查询相关键，确认最终状态后再决定下一步操作。

#范围与前缀扫描

let txn = db.begin()
let cursor = txn.scan_prefix(b"notes/")
while cursor.next() is Some((key, value)) {
  println("\{key}: \{value}")
}
txn.abort()

#调用者文件元数据示例

moon run src/cmd/metadata --target native

#显式迁移 v1

@vellum.migrate_v1("old.db", "converted.db")
let converted = @vellum.open("converted.db")

#使用前须知

• 同一路径只打开一个 Db。 没有文件锁，同一进程或不同进程同时写入会损坏数据；没有并行读快照。
• open 会把整个库载入内存并验证结构，内存占用随库大小增长。删除后的空间会复用，但文件不会缩小。
• 固定 4096 字节页。单个 value 最多 4000 字节，且 key.length() + value.length() <= 4085；键和值不能跨页，分支分隔键也必须能放进页。超限抛 ValueTooLarge。
• 格式 v2 使用无符号字节字典序：首个不同字节决定大小，相同前缀的短键在前，例如 b"aa" 在 b"z" 之前。空键、空值及任意二进制键均可使用；get 返回独立拥有的值。
• 普通 open 仅接受 v2，不自动升级。有效 v1 shortlex 库报无载荷 UnsupportedFormat；先只读覆盖已提交 WAL 再验证，拒绝时不回写主文件、不创建或清空源 WAL。坏头、节点、图或完整 WAL 帧仍报 Corrupt。显式迁移见上节。
• 主文件与 WAL 都显式同步。恢复覆盖进程中断及日志记录页的部分写入，不能补回日志中没有的缺失页。首次创建的父目录项未同步，尚未验证整机掉电耐久性。
• 数据页没有 CRC，value 的位翻转不一定能检出；WAL 完整帧损坏会报 Corrupt，但 v2 沿用原有日志结构，没有事务级页数或摘要，不能保证检出按完整帧边界丢失的日志。恢复不是备份。

#0.4.0

#0.3.0

moon run src/cmd/bench --target native --release

#固定结果的扫描规模对照

moon run src/cmd/scan_bench --target native --release

#开发

set -eo pipefail
curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash -s -- "$(cat .moonbit-toolchain)"
export PATH="${MOON_HOME:-$HOME/.moon}/bin:$PATH"
moon version --all
moonc -v
moon update

moon fmt --check
moon check --target native --deny-warn
moon test --target native
moon test src --target wasm-gc

moon run --target native --release src/cmd/main
moon run --target native --release src/cmd/bench
moon run --target native --release src/cmd/metadata
moon run --target native --release src/cmd/scan_bench

#0.4.1 - 2026-10-27

• 开发与 CI 工具链固定到 0.10.17+d971670cd，对应 CLI 0.1.20261023；第三方依赖版本不变。
• 首次发布 0.4 系列的 v2 格式、事务游标、显式 v1 迁移和元数据示例；既有 v1 数据库须显式迁移。

#许可证