131 lines
7.8 KiB
Markdown
131 lines
7.8 KiB
Markdown
---
|
|
markup: occlusion
|
|
title: Data resources — database, cache, storage and forms
|
|
import:
|
|
cache_api: ext/data/cache.mq.md
|
|
db_api: ext/data/db.mq.md
|
|
fs: lib/fs.mq.md
|
|
path: lib/path.mq.md
|
|
result: 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](db.mq.md) owns schemas and
|
|
transactions, [cache](cache.mq.md) owns expiry, [storage](storage.mq.md) owns blobs and upload
|
|
validation, and [forms](form.mq.md) separates validation, rendering and submission.
|
|
[View queries](view.mq.md) (中文:[视图](视图.mq.md)) retain current records inside recursive View nodes.
|
|
[Native administration](admin.mq.md) exposes only mounted forms and their business tables.
|
|
中文作者可以使用[表单](表单.mq.md)构造、定义字段规则、引用与挂载资源,使用[后台](后台.mq.md)启用同一个原生管理入口。
|
|
[JSON query routes](api.mq.md) 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.
|
|
|
|
```sh
|
|
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](cache_api.cache(url="memory:"))**.
|
|
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](fs.resolve(path="."))** and **expected_root = [Check the optional explicit root](fs.resolve(path=`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](fs.temp_dir(prefix="data-manual"))**.
|
|
The filesystem helper returns a root-relative name. We retain **work_dir = [Resolve the owned name through the actual filesystem context](fs.resolve(path=`directory`))**
|
|
and **[Check that this absolute directory is inside the granted filesystem root](fs.stat(path=`work_dir`))**
|
|
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](db_api.db(url=`database_url`))**.
|
|
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](access(native, "txn"))**
|
|
and **connection = [Read its connection URL](access(native, "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.
|