Skip to content

Database access

The db provider lets an agent answer questions straight from your plant database. It adds two read-only tools:

Tool Does
db_query runs one ad-hoc, read-only SQL statement against a connection you have opted in
named_query_exec runs an existing project Named Query

Both are read-only, so they work under the default readOnly: true posture. Nothing is exposed until you enable the provider and name the connections.

Turning it on

"providers": { "db": true },
"db": { "connections": ["MyDbConnection"] }

Two independent settings control access:

  1. providers.db must be true. An absent key means disabled.
  2. db_query refuses every connection not named in db.connections.

Both are on the settings page (Home → Artek MCP → MCP Server): the provider in the Providers table, the connections in the Database access card, which lists the gateway's real connections as checkboxes.

An empty db.connections means none, not all

Enabling the provider alone exposes no database. Name each connection, or deliberately opt in every connection with a single "*" entry (the Allow ALL connections toggle). The wildcard is always an explicit choice, never a default. The card warns when the provider is enabled with nothing opted in.

A key can carry its own dbConnections list as a third, narrowing setting. See Per-key scoping.

named_query_exec is governed by provider enablement only. A Named Query's connection is part of its own reviewed definition, not something the caller chooses, so db.connections and per-key dbConnections apply to db_query only.

Unknown versus denied. db_query reports a connection name that does not exist as "No such gateway database connection", and one that exists but is not opted in as "exists on this gateway but is not opted in", so you can tell a typo from a policy decision.

How a query is kept read-only

Protection is layered, strongest first:

  1. A read-only database user on the gateway connection. This is the layer you supply, and the only one the module cannot guarantee itself. Use one.
  2. A transaction that is always rolled back, marked READ ONLY on PostgreSQL and MySQL/MariaDB, with the JDBC read-only flag, a row limit and a query timeout. The rollback is what undoes a write on drivers that ignore the read-only flag. The connection's settings are restored before it returns to the gateway's pool.
  3. Statement checks. The statement must start with SELECT, WITH, SHOW, DESCRIBE or EXPLAIN, must be a single statement (no ;), and is refused if it contains, anywhere including literals and comments, INTO (including INTO OUTFILE and INTO DUMPFILE), FOR UPDATE, embedded data changes, or statements a rollback cannot undo: EXEC, DDL, GRANT, REVOKE, DENY, server-control commands, xp_ and sp_ procedures, OPENROWSET, OPENQUERY, dblink, sequence and backend-control functions, COPY, LOAD DATA, LOAD_FILE and MySQL /*! executable comments.

Named queries

named_query_exec:

  • refuses a Named Query of type UpdateQuery;
  • checks the parameters you pass against the query's declared parameter names;
  • runs through the gateway's own named-query engine, the same as system.db.runNamedQuery in Gateway scope;
  • refuses any query that declares a QueryString or Database parameter, or whose connection is <Parameter>. Only Value parameters, which the platform binds safely, are accepted.

Result limits

Setting Default Limits
limit (tool argument) 100 rows capped at db.maxRows
db.maxRows 1000 rows per result
db.maxCellChars 4096 characters per cell
db.maxResponseChars 200000 characters per response

The three db.* settings are read on every call, so a change takes effect immediately; any value above 0 is accepted. Raise them for large paged pulls of wide text columns. The database itself is still asked for at most limit + 1 rows.

Both tools always report rowCount, truncated and maxRows (plus totalRows for a Named Query), so a short result is never mistaken for a complete one. NaN and infinite values are returned as the strings "NaN", "Infinity" and "-Infinity".

Column redaction. A column whose name matches the secret vocabulary (password, token, apikey and similar) returns «redacted» and is marked redacted: true. The column still appears, so the result shape stays honest. Redaction is by column name only: alias derived columns neutrally, and do not rely on it for secrets stored under other names.

Exposure

Enabling this provider widens what every key can read

Row data is reachable through no other Artek-MCP tool. Enabling the db provider widens a read-only key from "can read project source, tags and configuration" to "can read the business database". A result carries no sign of which database it came from, so on a test gateway whose connection points at shared or production infrastructure, an agent reads production data. Opt in only the connections an agent needs, use a read-only database user, and narrow keys with dbConnections.