db connectors
The config fields of a db connector, which backs PostgreSQL, MySQL, SQLite and MongoDB.
Runs parameterized queries against PostgreSQL, MySQL, SQLite, or MongoDB. The connection_string scheme selects the backend: postgres://, mysql://, sqlite:, mongodb://, or mongodb+srv://. There is no driver field.
{
"name": "orders-db",
"connector_type": "db",
"config": {
"type": "db",
"connection_string": "env://ORDERS_DB_URL",
"max_connections": 10,
"connect_timeout_ms": 5000,
"query_timeout_ms": 30000
}
}
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
connection_string | string | yes | — | Database URL; the scheme selects the backend. Carries credentials, and is always masked in API reads |
max_connections | integer | no | — | Connection pool maximum size |
connect_timeout_ms | integer | no | — | Connection establishment timeout; also caps MongoDB server selection |
query_timeout_ms | integer | no | — | Per-query timeout |
allow_private_urls | boolean | no | false | Allow private and internal IP addresses (SSRF protection). Ignored for sqlite:, which opens a file |
operations | object | no | all allowed | read / insert / update / delete / upsert / raw_write — see Operation gates |
dialect | object | no | both guards off | Dialect guards |
aggregate_write_stages | boolean | no | false | MongoDB only: permit the $out/$merge write stages in mongo_aggregate pipelines. The one default-deny gate — an aggregation must not silently write |
There are two ways to talk to it. The portable data_query / data_write dialect runs unchanged against SQL, MongoDB and Elasticsearch. The other is raw SQL through db_read / db_write.
There is no retry field: a statement that timed out may already have been applied, so database calls are never re-driven. See Retries. Bound the call with connect_timeout_ms and query_timeout_ms instead.
Note
A
mongodb://ormongodb+srv://scheme makes this a MongoDB connector.data_queryanddata_writerun against it unchanged (pass adatabasefield in the task input); the raw-native surface is themongo_read/mongo_write/mongo_aggregatetrio, whose documents are extended JSON ($oid,$date, nested shapes).
Dialect guards
db and es connectors carry a dialect block that bounds what the portable dialect may reach. Operation gates answer which verbs; dialect guards answer which tables. Both guards default to off.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
require_schema | boolean | no | false | Refuse any data_query / data_write call without a real schema: at least one declared entity, and not "unmapped": "identity" |
allowed_entities | array of strings | no | [] (unrestricted) | Physical table, collection, or index names the dialect may touch. Matched after schema renames apply; covers relation targets and junction tables |
Unknown keys inside dialect are refused on create and update.
Related
- Connector types: every type, and the shared blocks all of them carry.
- Task functions: the functions that call through a connector.
- Portable data dialect: the language
data_queryanddata_writespeak. - Operation gates: the
operationsblock this type carries. - Definition and identity: the row the
configsits in.
Last verified 14 September 2026