原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同, 翻转会让 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
240 lines
6.3 KiB
Markdown
240 lines
6.3 KiB
Markdown
---
|
|
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`
|
|
2. *
|
|
> 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](access(self, "url"))**
|
|
*> web_db_init url=`url` name=`name` fields=`fields`*
|
|
|
|
## insert
|
|
+ `table`
|
|
+ `rows`
|
|
+ `txn`=None
|
|
|
|
**url = [url](access(self, "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](access(self, "url"))**
|
|
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
|
|
*[rows](access(r, "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](access(self, "url"))**
|
|
*> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`*
|
|
|
|
## get
|
|
+ `table`
|
|
+ `id`
|
|
+ `txn`=None
|
|
|
|
**url = [url](access(self, "url"))**
|
|
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
|
|
|
|
## update
|
|
+ `table`
|
|
+ `id`
|
|
+ `row`
|
|
+ `txn`=None
|
|
|
|
**url = [url](access(self, "url"))**
|
|
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
|
|
|
|
## delete
|
|
+ `table`
|
|
+ `id`
|
|
+ `txn`=None
|
|
|
|
**url = [url](access(self, "url"))**
|
|
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
|
|
|
|
## exec
|
|
+ `sql`
|
|
+ `args`=None
|
|
+ `txn`=None
|
|
|
|
**url = [url](access(self, "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](access(self, "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](access(self, "url"))**
|
|
**r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`**
|
|
*[count](access(r, "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](access(self, "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](access(self, "url"))**
|
|
*> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`*
|
|
|
|
## search
|
|
+ `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](access(self, "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](access(self, "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](access(self, "url"))**
|
|
**txn = [txn](access(self, "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](access(self, "url"))**
|
|
**txn = [txn](access(self, "txn"))**
|
|
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
|
|
*[rows](access(r, "rows"))*
|
|
|
|
## get
|
|
+ `table`
|
|
+ `id`
|
|
|
|
**url = [url](access(self, "url"))**
|
|
**txn = [txn](access(self, "txn"))**
|
|
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
|
|
|
|
## update
|
|
+ `table`
|
|
+ `id`
|
|
+ `row`
|
|
|
|
**url = [url](access(self, "url"))**
|
|
**txn = [txn](access(self, "txn"))**
|
|
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
|
|
|
|
## delete
|
|
+ `table`
|
|
+ `id`
|
|
|
|
**url = [url](access(self, "url"))**
|
|
**txn = [txn](access(self, "txn"))**
|
|
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
|
|
|
|
## exec
|
|
+ `sql`
|
|
+ `args`=None
|
|
|
|
**url = [url](access(self, "url"))**
|
|
**txn = [txn](access(self, "txn"))**
|
|
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
|
|
|
|
## 提交
|
|
|
|
Commit the transaction and return its connection to the pool.
|
|
|
|
**txn = [txn](access(self, "txn"))**
|
|
*> web_db_commit txn=`txn`*
|
|
|
|
## 回滚
|
|
|
|
Roll the transaction back (undo every write) and return its connection.
|
|
|
|
**txn = [txn](access(self, "txn"))**
|
|
*> web_db_rollback txn=`txn`*
|
|
|