Files
marqdo/ext/data/index.mq.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

7.8 KiB
Executable File

markup, title, import
markup title import
occlusion Data resources — database, cache, storage and forms
cache_api db_api fs path result
ext/data/cache.mq.md ext/data/db.mq.md lib/fs.mq.md lib/path.mq.md lib/result.mq.md

Start here when a program needs persistent records, short-lived values, object storage or forms. The public resource files remain the implementation: database owns schemas and transactions, cache owns expiry, storage owns blobs and upload validation, and forms separates validation, rendering and submission. View queries (中文:视图) retain current records inside recursive View nodes. Native administration exposes only mounted forms and their business tables. 中文作者可以使用表单构造、定义字段规则、引用与挂载资源,使用后台启用同一个原生管理入口。 JSON query routes bind read-only database responses to a prepared site; pair tenant-scoped queries with the explicit security tenant resource.

These modules use the native web plugin. In this source checkout build it with scripts/build-web-plugin.sh; installed packages follow the web package installation route. Commands below run at the repository root. The cache example uses memory only. The transaction example creates a SQLite file in an owned temporary directory. Prepare an existing disposable directory and export MQ_WORK to its absolute path; the transaction report returns work_dir for cleanup after this process exits. Neither example needs a cloud account, credentials or an external service.

marqdo call ext/data/index.mq.md memory_cache 'key="manual"' 'value="ready"' --effects plugin --json
marqdo call ext/data/index.mq.md transaction_roundtrip --effects plugin,fs.write --fs-root "$MQ_WORK" --json

A resource constructor creates an object; its methods need that actual receiver. Use the free workflow tools below for a single CLI call, or import the resource file and keep the object in your program. Do not pass an instance method to call without its receiver or reconstruct a transaction from guessed fields. Native resource URLs select their own backend: the marqdo filesystem root does not rewrite a SQLite, S3 or Redis URL. Grant plugin access deliberately.

For development, keep backend operations in the native web resource implementation and expose small, documented compositions here. Specify row/filter shapes, transaction ownership, conflicts, expiry units and cleanup. Add an operation to its responsible leaf file and exercise it through this facade or a real author program. Run the source-handbook regression and database/cache gold cases on both backends. A successful transport record is not proof that a business update matched.

memory_cache

参数 类型 默认 说明
key text "manual" Key owned by this short-lived demonstration
value any "ready" Value written and then read back from the in-process cache
返回 类型 说明
result any Actual cache get result; value contains the stored value

Use key="manual" and value="ready" unless the caller supplies different data. This workflow uses memory: storage, so values belong to the current native plugin process. It removes its key after reading; do not use a production key for an illustrative roundtrip.

First cache = Create a process-local cache. We then [Store the supplied value with a sixty-second expiry](> cache.set key=key value=value ttl=60 ) and retain stored = [Read the same cache entry](> cache.get key=key ). Once the value has been captured, [Remove the demonstration key](> cache.del key=key ) so another operation does not inherit it. Return stored as observed, including its backend fields.

transaction_roundtrip

参数 类型 默认 说明
root text "." Expected filesystem root; the default uses the actual --fs-root context
返回 类型 说明
result map The committed row list and native commit/rollback outcomes; the second insert is rolled back

Use root="." for the actual --fs-root context, or pass the same absolute root explicitly. This isolated-file example shows the whole ownership sequence: create a schema, begin a transaction, write through its receiver, finish it, and read outside it. A second transaction is explicitly rolled back. The standalone txn constructor wraps the actual native identifier and connection URL; it does not begin another transaction or invent an identifier.

We actual_root = Resolve the actual granted filesystem root and expected_root = Check the optional explicit root.

  1. actual_root != expected_root Return [Keep an inconsistent resource root explicit](result.error(code="data.root", message="root must match the granted filesystem root", operation="transaction_roundtrip")). First directory = Create an owned temporary directory under the granted root. The filesystem helper returns a root-relative name. We retain work_dir = Resolve the owned name through the actual filesystem context and Check that this absolute directory is inside the granted filesystem root before giving any path to the native database. We select database_path = [Choose the SQLite file inside that directory](path.join(a=work_dir, b="manual.db")) and select database_url = "sqlite:" + database_path before creating the receiver store = Open only that explicitly selected SQLite resource. The table schema is ordinary readable data; both columns and their nullability remain visible.

fields =

字段 类型 可空
title text False
body text True

We [Create the isolated demonstration table](> store.init name="manual_notes" fields=fields ) before borrowing the transaction connection. Next native = [Begin the first transaction](> store.事务 ). To retain the exact identifier, identifier = Read the returned transaction identifier) and connection = Read its connection URL). Now transaction = [Wrap those actual fields as a transaction receiver](db_api.txn(txn=identifier, url=connection)).

row =

title body
committed kept

We [Insert the first row inside its transaction](> transaction.insert table="manual_notes" rows=row ) and keep committed = [Commit that transaction](> transaction.提交 ). The second cancelled = [Begin an independent transaction](> store.事务 ) is a native transaction receiver, which can be used directly because its type and resource fields are retained. We [Insert a row that will be discarded](> cancelled.insert table="manual_notes" rows=row ) then capture rolled_back = [Roll back the second transaction](> cancelled.回滚 ). Finally rows = [Read the committed state outside a transaction](> store.select table="manual_notes" order="id" ).

report =

rows committed rolled_back work_dir
rows committed rolled_back work_dir

This example ends with one committed row. Real programs must also arrange rollback when a later operation fails. This plugin pools open connections, so remove the owned work_dir only after this CLI process exits and the connection is closed, including on failure. Do not assume sqlite::memory: is in-memory through this ABI: relative resource paths are resolved against the module directory. Return report with the real row data, completion records and cleanup location.