Files
marqdo/ext/data/index.mq.md
T

6.8 KiB

markup, title, import
markup title import
occlusion Data resources — database, cache, storage and forms
cache_api db_api fs path
ext/data/cache.mq.md ext/data/db.mq.md lib/fs.mq.md lib/path.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.

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 "root=\"$MQ_WORK\"" --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 required Absolute disposable root, matching --fs-root; native resource URLs need an absolute path
返回 类型 说明
result map The committed row list and native commit/rollback outcomes; the second insert is rolled back

Use the absolute root supplied for --fs-root. 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.

First directory = Create an owned temporary directory under the granted root. The filesystem helper returns a root-relative name. We retain work_dir = [Resolve that owned name against the explicit root](path.join(a=root, b=directory)) 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.