Databases

Define a database in global.databases (reused across actions) or inline on an action. Connect with a driver + conn_string, or with discrete user/pass/host/dbname fields — don't mix the two.

Supported drivers: postgres, mysql, mssql, sqlite, mongodb (also Azure Cosmos DB and Amazon DocumentDB via the MongoDB driver).

global:
  databases:
    main:
      driver: postgres
      conn_string: "postgresql://a|env::PG_USER|:a|env::PG_PASS|@a|env::PG_HOST|/app"

interfaces:
  users:
    method: GET
    actions:
      - name: List
        database: main
        query: SELECT * FROM users

Pass request values to a query with params (params: [a|body::email|]), not input:. An input: read from the request (a|body|, a|params|, ...) is used instead of running the query: the action answers with the request and the query never runs. Validation refuses a database action with both, and config load warns about it.

When the database cannot be reached or rejects the query, the action answers 503 or 500, even if its own assert would answer something else — see When the step itself fails.

Document stores

NoSQL / document stores use a document_operation block instead of query — database, collection, operation (find, findOne, insertOne, updateMany, aggregate, …) and the relevant filter / pipeline / insert / update / delete / options. Full fields are in the DocumentOperation type below.

Database

Field	Type	Description
driver	string (nullable)
conn_string	string (nullable)
user	string (nullable)	Default: null.
pass	string (nullable)
host	string (nullable)	Default: null.
port	number (nullable)
dbname	string (nullable)	Default: null.
params	string (nullable)	Default: null.
auth_source	string (nullable)
max_open_conns	number (nullable)
max_idle_conns	number (nullable)
conn_max_lifetime	any
timeout	any
synchronous	string (nullable)	SQLite-only: PRAGMA synchronous (OFF | NORMAL | FULL | EXTRA). Defaults to NORMAL (with WAL journaling) when unset — durable against application/process crashes and…

DocumentOperation

Field	Type	Description
database	string	Required. Database name on the connection — the Mongo/Cosmos/DocumentDB database, not the database: key of the action, which names the connection in global.databases.
collection	string	Required. Collection to operate on.
operation	string	Required. Which operation to perform. The engine dispatches on this string, and an unrecognised value fails the action rather than defaulting to anything. Supported: find, findOne,…
filter	any	Query selector, for the read, update and delete operations. Example ↓
pipeline	any	Stages for aggregate. Ignored by every other operation.
insert	any	Document(s) to write, for insertOne and insertMany.
delete	any	Reserved for delete payloads; filter selects what a delete removes.
update	any	Update document, for updateOne and updateMany — including its operators, e.g. {"$set": {...}}.
options	any	Driver options passed through for this operation, such as projection, sort, limit or upsert. Which keys apply depends on the operation.

Field examples

filter

Query selector, for the read, update and delete operations.

filter: '{"email": "a|body::email|"}'