Skip to content
Querion

Querion / Reference

Safety model

Exactly what Querion allows and refuses for SQL, HTTP and user requests, described from the code that enforces it.

On this page
  1. First principles
  2. The layers
  3. 1. SQL validation
  4. Consequences to know
  5. 2. Read-only session and timeout
  6. 3. HTTP requests
  7. 4. The write-request firewall
  8. What the model can do
  9. Practical checklist

This page describes what the code in querion/safety.py, querion/db.py, querion/sources.py and querion/engine.py actually does. It also lists where the checks stop, so you can decide what your database role and application programming interface (API) tokens must cover.

The short version: application-level checks are a backstop. The strongest guarantees are a read-only Postgres role and read-only API tokens, which you control.

First principles

Querion changes outside state only if one of its two executors sends a write. The Structured Query Language (SQL) executor talks to Postgres. The Hypertext Transfer Protocol (HTTP) executor talks to your APIs. The model itself cannot reach either; it can only ask, in text. So the safety question has two parts: what can reach each executor, and what the system at the other end permits.

The second part decides the outcome. A role with only SELECT grants cannot write, whatever text arrives. A token with read-only scopes cannot change anything, whatever path is requested. Code in Querion can refuse requests before they leave, but it reasons about text, and text checks have gaps. The sections below show where those gaps are.

The layers

  1. Your read-only database role (not code in Querion).
  2. SQL validation before a query is sent.
  3. A read-only database session with a statement timeout.
  4. HTTP requests that are always GET, with an optional per-source allowlist.
  5. A write-request firewall, partly deterministic and partly model-driven.

1. SQL validation

validate_sql runs before every query, including the schema introspection queries. It raises an error, and nothing is sent to Postgres, in these cases:

  • The query is empty.
  • A semicolon appears anywhere except as trailing semicolons. Multiple statements are refused.
  • The first word is not select or with (case-insensitive). A query that starts with a comment, a parenthesis or EXPLAIN is therefore refused, and so is select*from, where no space follows the keyword.
  • The text contains any of these words as a whole word, case-insensitive: insert, update, delete, drop, alter, truncate, grant, revoke, create, comment, copy, vacuum, analyze, reindex, cluster, listen, notify, do, call, merge, lock, set.

The keyword check covers data-modifying common table expressions (CTEs) such as WITH x AS (DELETE ... RETURNING ...) SELECT ....

Consequences to know

  • The keyword check is a plain text match over the whole query. It also matches inside string literals and identifiers that are exactly one of those words. WHERE note = 'set' or a column named comment is refused, even though the query is harmless. created_at is not affected, because underscores are part of the word.
  • The denylist does not include INTO or function calls. For example SELECT ... INTO new_table and calls to functions such as set_config(...) or pg_sleep(...) pass validation. They are stopped, or bounded, by the role and the read-only session (layers 1 and 3), not by this check.
  • Because a semicolon anywhere inside the query text (including inside a string) is refused, literals containing ; fail.

2. Read-only session and timeout

querion/db.py opens a new connection for each query. It uses connect_timeout=5 and psycopg2’s set_session(readonly=True, autocommit=True). It then runs SET statement_timeout with database.statement_timeout_ms and executes the query. Rows are fetched with fetchmany(row_cap + 1), so a large result is cut at row_cap. The connection is closed afterwards.

Postgres rejects writes in a read-only session, which is why this layer matters more than the keyword list. It still relies on Postgres behavior, so pair it with a role that has only SELECT grants and default_transaction_read_only = on.

querion check reports the database as ok (read-only) after running SELECT 1. That proves the connection string works. It does not inspect the role’s privileges.

3. HTTP requests

Every request Querion sends uses requests.get. No other method is ever issued.

The directive text goes through read_verb first:

  • POST, PUT, PATCH and DELETE as the first word raise an error: “is a write and is not allowed - reads only”.
  • GET and HEAD are accepted, and HEAD is sent as a GET.
  • A bare path is treated as a GET.
  • Any other first word (for example OPTIONS) is not treated as a verb. The whole text becomes part of the path, so it is checked against the allowlist and sent as a GET to that odd path.

Then the path is checked against the source allowlist, if one exists. With safe_get set, a path that does not match is refused with a message naming the source. With no safe_get, any GET path is allowed. Details of matching are in Connecting data sources.

What this does not cover:

  • A GET that changes state on the server. That is exactly why the allowlist exists, and why an API token with read-only scopes is the real protection.
  • Dot segments. The allowlist matches the raw path text and does not normalize .. segments. /v1/customers/../admin matches ^/v1/customers, but it can resolve to /admin on its way to, or on, the server. A pattern that refuses .. is shown in Connecting data sources.
  • The query string. Only the path is checked. The query string is free text, so anything the model has read, including rows from Postgres, can be sent to a configured source as a query parameter. Keep secrets out of the tables the role can read.

Refused paths, network errors and other exceptions are returned to the model as text such as <name> GET failed: ..., so it can adjust.

4. The write-request firewall

The engine runs write_request_reason on the user question before any model call. It is deterministic and looks only for explicit statements pasted into the question:

  • INSERT INTO ... followed by a column list, VALUES or SELECT.
  • UPDATE <table> SET.
  • DELETE FROM <table> followed by WHERE, a semicolon or end of text.
  • TRUNCATE TABLE, DROP TABLE|SCHEMA|DATABASE|ROLE|VIEW, ALTER TABLE|ROLE|DATABASE|SYSTEM.
  • CREATE TABLE ... (, CREATE DATABASE|SCHEMA|ROLE|EXTENSION.
  • GRANT SELECT|ALL|INSERT|UPDATE|DELETE and REVOKE ... ON.
  • A GraphQL mutation.

A match returns status refused and no model call is made. The web server does the same check first, without spending the caller’s daily quota.

Requests written in ordinary English, such as “Cancel order 14377”, “Update the price of SKU X” or “Delete the test customers”, are not matched by that pattern. For those, the system prompt tells the model to reply with a first line starting with [WRITE-REQUEST-BLOCKED] and to run nothing. The engine checks whether the reply starts with that marker, ignoring leading whitespace, and returns a refusal. A reply that puts the marker anywhere else is not treated as a refusal.

So the English-language refusal depends on the model following its instructions. It is not a deterministic filter. If the model ignores the instruction and emits a write, the other layers stop it: the role, SQL validation, the read-only session and the HTTP checks. Questions about past changes, such as “which orders were cancelled last week?”, are treated as normal analytics.

What the model can do

The model cannot run anything itself. The claude command-line interface (CLI) is started with file, shell, web and task tools disallowed, and with no Model Context Protocol (MCP) servers. Only three directives are executed, each in a fenced block: run-sql, source:NAME and chart. A plain sql block in an answer is display only and never runs. Unknown source names return an error message.

Two limits of that boundary:

  • The tool list is a list of names. --disallowed-tools names Bash, Edit, Write, Read, Glob, Grep, WebFetch, WebSearch, NotebookEdit and Task. A tool that a later CLI version adds or renames is not on that list.
  • Data reaches the prompt. Query results and API responses are fed back to the model as text. Content in your data that reads like an instruction could steer the next directive. Every directive still passes the checks above, so the effect is bounded by what the role and the allowlist permit.

Practical checklist

  • Use a database role with SELECT only and default_transaction_read_only = on.
  • Revoke access to tables that hold secrets. Anything the role can read can reach the model, and through a query string, a configured API.
  • Use read-only API tokens where the platform offers them.
  • Set safe_get on every source that is not strictly RESTful, and anchor the patterns.
  • Do not expose querion serve without authentication. See CLI and web API.