7.8 KiB
markup, title, import
| markup | title | import | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| occlusion | Data resources — database, cache, storage and forms |
|
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.
actual_root!=expected_rootReturn [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.