Default execute/sse-live/stream to Supervisor worker pool; MR-01 gold; /_runtime/*; bump CLI/wasm/ext to 2.1.4. Co-authored-by: Cursor <cursoragent@cursor.com>
254 lines
6.8 KiB
Markdown
254 lines
6.8 KiB
Markdown
---
|
|
markup: occlusion
|
|
title: ext/data/db
|
|
description: Database Resource — CRUD, txn, migrate, FTS (ADR 0007).
|
|
import:
|
|
plugin: lib/plugin.mq.md
|
|
sys: lib/sys.mq.md
|
|
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`*
|
|
|
|
## update_if
|
|
+ `table`
|
|
+ `id`
|
|
+ `row`
|
|
+ `expect_col`
|
|
+ `expect_val`
|
|
+ `txn`=None
|
|
|
|
Conditional update (CAS) for task/revision control: `UPDATE … WHERE id=? AND expect_col=expect_val`. Returns `{ ok, updated, matched }`; `updated=0` means conflict — do not simulate atomicity with read-then-write in `.mq.md`.
|
|
|
|
**url = [url](access(self, "url"))**
|
|
*> web_db_update_if url=`url` table=`table` id=`id` row=`row` expect_col=`expect_col` expect_val=`expect_val` 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`*
|
|
|