Files
marqdo/ext/data/db.mq.md
T
cflmy 4488a3cb70 feat(migrate): M7 迁移与版本门 — per-file markup + migrate labels + 全仓迁移
原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同,
翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。

一、per-file markup
- frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式
- load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析
- 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认
- 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义

二、`marqdo migrate labels [--write|--json]`
改写规则:
  [键](集合)      → [键](access(集合, "键"))
  [`名`](集合)    → [名](access(集合, `名`))
  - [项](集合)    → - [项](遍历 集合 为 项)

安全模型:改写 → 重解析 → 证明等价 → 才写
- 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B
- 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index)
- Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动

只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰;
链式索引由内向外改写,已迁移的有守卫不二次改。

三、access 提升为宿主函数 HostFn::Access(u16 id 212)
与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key);
进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。

四、顺带修的两处真实语义缺陷
1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用
   → `()` 内永远允许 callee(args)
2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽
   → 要求 `]` 后紧跟 `(`,否则落回方括号调用

五、全仓迁移结果
migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝;
迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。

等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、
遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。

测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 /
等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。

文档:doc/design/change-m7-migration.md
2026-10-22 15:33:31 +08:00

6.3 KiB


markup: occlusion title: ext/data/db description: Database Resource — CRUD, txn, migrate, FTS (ADR 0007). import plugin:lib/plugin.mq.md import sys:lib/sys.mq.md import table:lib/table.mq.md

_load

p = > plugin.native_path name="web"

  1. p

plugin.load path=p

print text=ext/data: native web plugin not found sys.exit code=1


db

+ `url`="sqlite:site.db"

Open a database handle. URL schemes: sqlite:path (default), postgres://… / postgresql://… (same CRUD methods).

_load > web_db_new url=url

init

+ `name`
+ `fields`

Create a table from a schema table. Optional columns: 唯一/unique, 索引/index (creates UNIQUE / INDEX), 外键/fk/references (e.g. posts.id or posts(id)). Columns named created_at / updated_at are filled automatically on insert/update when present.

url = url) > web_db_init url=url name=name fields=fields

insert

+ `table`
+ `rows`
+ `txn`=None

url = url) > web_db_insert url=url table=table rows=rows txn=txn

select

+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
+ `txn`=None

Simple filters: one-row map of column→value (AND =), or rows |字段|操作|值| (= != > >= < <= like in between is null; add |或| = 是 to join a row with OR). order is a column name with optional - prefix for descending ("created_at", "-created_at"), comma-separated for multiple keys. Pass txn to read inside an open transaction. For pages (with a total), use paginate.

url = url) r = > web_db_select url=url table=table where=where limit=limit order=order offset=None txn=txn rows)

paginate

+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
+ `跳过`=0
+ `txn`=None

Like select but returns { rows, total } — the total counts rows matching where regardless of limit/跳过, so you can render 上一页 / 下一页. Set 跳过 to the number of rows to skip (e.g. page 2 with 10 per page ⇒ 跳过=10).

url = url) > web_db_select url=url table=table where=where limit=limit order=order offset=跳过 txn=txn

get

+ `table`
+ `id`
+ `txn`=None

url = url) > web_db_get url=url table=table id=id txn=txn

update

+ `table`
+ `id`
+ `row`
+ `txn`=None

url = url) > web_db_update url=url table=table id=id row=row txn=txn

delete

+ `table`
+ `id`
+ `txn`=None

url = url) > web_db_delete url=url table=table id=id txn=txn

exec

+ `sql`
+ `args`=None
+ `txn`=None

url = url) > web_db_exec url=url sql=sql args=args txn=txn

query

+ `sql`
+ `args`=None
+ `txn`=None

Run bare SQL and return the result set — count / join / group / subqueries. Returns { rows, count }.

url = url) > web_db_query url=url sql=sql args=args txn=txn

count

+ `table`
+ `where`=None
+ `txn`=None

Count rows matching a where filter (same syntax as select). Returns a number.

url = url) r = > web_db_count url=url table=table where=where txn=txn count)

migrate

+ `steps`

Apply versioned SQL migrations. steps is a |version|sql| / |版本|SQL| table. Applied versions are recorded in _marqdo_migrations. Re-running is a no-op for already-applied versions. SQLite only.

url = url) > web_db_migrate url=url steps=steps

fts

+ `table`
+ `columns`
+ `name`=None

Create an FTS5 index on table for the listed content columns (CSV string or list). Default FTS name is {table}_fts. Keeps the index in sync via triggers. Requires integer id PK. SQLite only.

url = url) > web_db_fts_create url=url table=table columns=columns name=name

+ `table`
+ `q`
+ `limit`=20
+ `name`=None

Full-text search (MATCH) against the FTS5 index from fts. Returns { rows, count } with a rank column (bm25). SQLite only.

url = url) > web_db_search url=url table=table q=q limit=limit name=name

事务

Begin a transaction: borrows the pooled connection exclusively and returns a txn handle. Write inside it, then 提交 (commit) or 回滚 (roll back). Every statement runs on the same connection, so a batch is atomic.

url = url) > web_db_begin url=url

txn

+ `txn`
+ `url`

A transaction handle from db.事务. All CRUD here runs on the transaction's connection; finish with 提交 or 回滚.

self

insert

+ `table`
+ `rows`

url = url) txn = txn) > web_db_insert url=url table=table rows=rows txn=txn

select

+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None

Same filters as db.select; runs inside the transaction.

url = url) txn = txn) r = > web_db_select url=url table=table where=where limit=limit order=order offset=None txn=txn rows)

get

+ `table`
+ `id`

url = url) txn = txn) > web_db_get url=url table=table id=id txn=txn

update

+ `table`
+ `id`
+ `row`

url = url) txn = txn) > web_db_update url=url table=table id=id row=row txn=txn

delete

+ `table`
+ `id`

url = url) txn = txn) > web_db_delete url=url table=table id=id txn=txn

exec

+ `sql`
+ `args`=None

url = url) txn = txn) > web_db_exec url=url sql=sql args=args txn=txn

提交

Commit the transaction and return its connection to the pool.

txn = txn) > web_db_commit txn=txn

回滚

Roll the transaction back (undo every write) and return its connection.

txn = txn) > web_db_rollback txn=txn