The words QueryAPIGate uses

SQL a caller sends directly to /execute_sql or the MCP execute_sql tool, rather than a saved query. Only for keys granted a connection, one statement, read-only unless allowed, and confined to allowed_tables.

The four fixed administrator roles: owner (everything), admin (everything but administrators), developer (saved queries and collections, no keys) and auditor (read only, no SQL).

A named person or pipeline that manages QueryAPIGate, holding one of four fixed roles and signing in with their own admin tokens, so every change in the audit log has someone behind it.

Architecture decision record: a short, numbered document in the product repository that records a design decision, what was weighed and why. The docs cite them, as ADR 0028 for the data plane.

GET /api/v1/usage/agents: what each AI agent did over MCP, per agent: calls, rows, errors, masked calls, the queries and connections it used, its ad-hoc calls and what it was refused.

How an AI agent changes data: only through a saved query its author marked agent_writes, either held for a person’s approval (approval) or as a single idempotent insert (insert).

Live conditions worked out on each request, such as key_expiring or writes_awaiting_approval, shown in the Console and at GET /api/v1/alerts, and gone once the cause is.

The files a DuckDB connection may read: local folders, s3://, gs:// and r2:// prefixes, and single files on the web. Nothing outside the list can be read from SQL.

A grant that confines a key’s ad-hoc SQL to named tables. The SQL is parsed, not pattern-matched, and a table outside the list answers as if it did not exist.

The credential an application calls with, sent as X-API-Key. Stored only as a SHA-256 hash; it can be scoped, rate-limited, pinned to IP ranges, given an expiry and rotated.

A held agent write, wr_…, that an administrator with writes.approve approves or rejects in the Console. Once approved it runs once, for that caller, with exactly the arguments shown, before it expires.

The record of every administrative change: who changed what, with the fields that changed. Each entry is chained to the one before, and the log can stream to your SIEM.

QUERYAPIGATE_API_KEY: a full-access key that keeps working as an owner when the identity provider is down. Its use raises an alert.

GET /catalog: what the calling key may run, and on what terms, such as whether a query is cached, whether this key may write through it, and its rate limit.

A typed client generated from /openapi.json with openapi-generator, for Java, TypeScript, Go or any of about 50 languages. The spec is checked in CI against the official validator.

A named group of saved queries. A key or role granted a collection reaches every query in it, including ones added later; it can be renamed, exported, imported and handed out as a Postman collection.

Hiding a column from a caller: hash, mask, null or drop. Traced through aliases, CTEs and joins to the source column; a query whose columns can’t be traced is refused rather than answered unmasked.

What changes only with notice: REST endpoints and responses, CLI commands, environment variables, the storage format, grant fields, the saved-query format, the MCP tool contract and error codes.

config export, config diff and config apply: the whole setup as one YAML file with no secret in it, reviewed in a pull request and applied all or nothing.

A named database, or a folder or bucket of files, that QueryAPIGate reaches with its own credentials. Callers never see those credentials.

Database connections kept open and reused between requests, for every type but SQLite: QUERYAPIGATE_POOL_SIZE idle ones per connection setting, 8 by default. A connection used by a failed or timed-out request is closed, never reused.

The built-in administration UI at /console: connections, saved queries, keys and roles, a SQL editor, history, the audit log, alerts and approvals. Everything it does is also on the Management API.

Administrators sign in to the Console through your identity provider over OpenID Connect, with its MFA and policies, and their role comes from their groups. One provider at a time; no SAML.

Calling the API from a browser frontend on another origin. Off unless QUERYAPIGATE_CORS_ORIGINS names the origins allowed.

An MCP resource per connection, queryapigate://connections/<name>/dictionary, telling an agent what each table and column means and which columns are masked for it.

queryapigate-dataplane, a Rust process in the image that takes the public port and serves saved-query reads from plans the Python server gives it, forwarding everything else unchanged. Measured at 3-9x the calls a second per core, with every run still recorded; in the Helm chart, dataplane.enabled: true.

Plain-language notes on connections, tables, columns and parameters, imported from database comments or written by you, and given to agents and docs alike.

Where exports may write: an s3://, gs:// or r2:// prefix, or a local folder inside QUERYAPIGATE_EXPORT_DIRS, with credentials stored like a connection password. Every write goes through a DuckDB connection locked to that prefix.

A saved query has at most one published version: the one /q/<name> runs and OpenAPI, MCP and Postman describe. Newer versions are drafts, invisible to callers until published.

An embedded analytical database that also reads Parquet, CSV and JSON files where they are, on disk, in a bucket or on the web, with no import step. One type for a .duckdb file or for views over files; tier 1.

What every call passes, whichever front door it used: identify the caller, apply its limits, check the grant, validate parameters, guard the SQL, run it, mask and format, record it.

With QUERYAPIGATE_SECRET_KEY set to a Fernet key, every literal connection password is encrypted before it touches disk and decrypted only in memory when a connection opens. The ciphertext is never returned to a client.

queryapigate history forget jwt:<subject> deletes a signed-in person’s runs, events and usage counts, in the store and in Redis. The audit log records the erasure by the caller’s SHA-256, not their name.

The stable code field on every error, such as param_invalid or forbidden. Part of the compatibility promise: an existing code is never renamed or repurposed.

Every run, written to the store in the same batch as its history row. Live events come from it, so a client that reconnects with Last-Event-ID gets what it missed, nothing repeated. Kept 24 hours by default.

queryapigate events: a separate asyncio server from the same image that serves /events to many clients at once. The main server’s own GET /events holds a thread per stream, so it serves only a few.

Four worked scenarios installed by queryapigate examples load: reporting, dashboard data, a streaming export and a partner integration, each with a collection, a role and a ready key, removable with one command.

A feature that works but sits outside the compatibility promise until it graduates, labelled wherever you meet it.

queryapigate export or a saved export: a full result written to a file or a bucket through the same streaming path, incrementally from a watermark, with no server needed.

Running on a validated OpenSSL in FIPS mode, such as RHEL 9 or Ubuntu Pro FIPS, with Python and cryptography from the distribution rather than PyPI. Validation belongs to the cryptographic module, not to the application.

A parameter whose value comes from the caller’s sign-in token instead of the request, so a user can only ever ask for their own rows. A caller who sends it anyway is refused.

One of the ways a call arrives: REST, MCP, live events, exports or the Management API. All of them pass the same governance code.

db: "jdbc": any database with a JDBC driver, such as Oracle, SQL Server, DB2 or Snowflake, through an embedded JVM and the vendor’s driver jar. It has no query time limit and no schema browser.

What a key or role may reach: whole connections, named saved queries or collections, tables for ad-hoc SQL, and which writes, if any.

GET /health: public and never rate-limited, it answers the status, version and time zone. A load balancer skips an instance that fails it.

The Kubernetes chart, published with every release at the server’s version. store.type: sqlite runs one pod; store.type: postgres runs several on PostgreSQL with Redis, rolled one at a time.

Keycloak, Okta, Auth0, Entra ID or another OpenID Connect provider. It signs people in and issues the tokens QueryAPIGate checks, for signed-in users, the Console and AI clients; QueryAPIGate never sees a password.

GET /api/v1/instances: every serve, mcp and events process using the store, seen in the last 90 seconds, with its version, and problems such as instances whose versions differ.

/docs: Swagger UI over /openapi.json, listing every saved query as its own endpoint with its parameters, types and defaults. The SQL is never included.

allowed_ips: the addresses or CIDR ranges, IPv4 or IPv6, a key may be used from. A call from anywhere else fails like a wrong key, a 401 that says nothing about why.

expires_at: a date after which a key stops working on its own. It works through the end of that day, and it is checked on every request, so there is nothing to schedule.

POST /api/v1/api-keys/{name}/rotate: a new secret, shown once, while the old one keeps working for grace_minutes, 60 by default and at most a week. The name, grants and history stay.

last_used_at on a key: roughly when it last authenticated, updated at most once a minute. It shows a stale key to revoke, or a new one that was never wired up.

MCP tools for exploring a connection: its tables and columns, with types and keys, a masked column flagged as such. Listed only for a key with access to whole connections.

Server-sent events as saved queries run, per key if you want, from GET /events or the separate queryapigate events server for many clients.

/api/v1: everything the Console does, over HTTP, for scripts and pipelines.

The Model Context Protocol, the standard AI agents use to call tools. QueryAPIGate’s MCP server publishes saved queries as tools under the same rules as REST.

A published saved query as an agent sees it: a name, a description, an input schema built from its parameters, and structured results. mcp: false hides a query from MCP while it still serves REST.

QUERYAPIGATE_METADATA_CACHE_TTL: seconds the key, saved query and connection a call reads from the store are reused instead of read again. Off by default; a change through another instance is seen up to that long later.

/metrics: Prometheus text-format metrics, for a Grafana dashboard or alerting. Public unless QUERYAPIGATE_METRICS_TOKEN is set.

find() queries only, with filter, projection, sort and bound parameters, ad hoc or saved. Nothing else is ever sent, and server-side JavaScript such as $where is refused. Tier 1 since 0.37.

A hosted AI client signs in through your identity provider, following the MCP specification’s OAuth 2.1. QueryAPIGate is the resource server: it checks tokens and issues none.

/openapi.json: a standard OpenAPI 3.0 document of the API and every saved query. Postman and Insomnia import it by URL, and openapi-generator turns it into clients.

page and page_size (10 by default, at most 1000 unless the server says otherwise), within the statement’s own LIMIT. Responses carry X-Page, X-Page-Size and X-Has-More.

What a :name parameter accepts: type, default, required, enum, numeric range, length and pattern. Values are bound, never spliced into SQL, and a request breaking a rule gets a 400 listing every problem.

A columnar file format. ?format=parquet and exports write it on every database type through DuckDB, with decimals kept exact.

max_concurrent, query_timeout and max_rows on a key or role. Each narrows the server’s own limit, never widens it; over max_concurrent a call gets a 429, not a place in a queue.

A queries entry such as {"name": "submit_order", "allow_writes": true}: write access to that one query and nothing else. A wildcard never carries write access.

QUERYAPIGATE_QUERY_TIMEOUT, 30 seconds by default, enforced by each database itself so the statement is really cancelled. A request or a key can lower it, never raise it.

Calls and rows per day or month for a key, with X-Quota-Remaining-* headers on every response and an alert before it runs out.

A request budget: a server-wide limit by client address, and an optional per-key rate_limit. A request must pass both; over it, the answer is a 429 with retry_after.

Shared state for several instances: rate limits and the response cache. Optional for one instance, which it gives a cache that survives restarts; required for several.

An identifier on every response, X-Request-Id, also in the error body and on every log line written for that request.

Optional HTTP caching a saved query opts into with cache_ttl: ETag, conditional requests and 304, never for a query that writes. In-process, or shared through Redis.

json, ndjson, csv, tsv, xml, yaml, xlsx or parquet, chosen with ?format=. The first is the default.

A reusable template of grants and limits, copied onto a key once when the key is created. Editing or deleting a role later never changes a key made from it.

Replacing instances on one store one at a time, with no downtime. Within 1.x a release changes the store only by adding to it, so instances still on the previous release keep working; CI checks it.

The record of each run: when, which connection, which key, through which front door, how long and how many rows. MCP runs carry "transport": "mcp".

QUERYAPIGATE_RUN_STORE_URL: run history, the event log and usage rollups kept in ClickHouse instead of the store, for a data plane’s rates. Keys, queries and the audit log stay where they are. A prototype.

SQL with a name, description, parameters, permissions and optional cache settings, published as GET /q/<name>, an MCP tool and an export from the one definition.

A connection’s tables and views, with columns, types, nullability and keys, in the Console and at GET /connections/<name>/schema.

An API key restricted to a set of connections, an allow-list of saved queries or collections, or both, so it reaches only what it was given.

${VAR}, ${file:...} or ${vault:...} in place of a password, resolved when it is needed, so the secret is never kept in the store. Vault can also issue short-lived database credentials.

nosniff, a Content-Security-Policy, no-referrer, no-store and, when configured, HSTS, set on every response by the server itself rather than left to a proxy.

A text parameter marked "embed": true: the server turns the caller’s words into an embedding and binds it, so the SQL can rank rows by pgvector similarity. PostgreSQL only, and off unless an embeddings endpoint is set.

Any number of interchangeable instances behind a load balancer, sharing a PostgreSQL store and Redis. The reference deployment is three instances behind Caddy in one Compose file.

Every audit entry, as it is written, to Splunk, Sentinel, Elastic, QRadar or a log forwarder, over syslog with TLS or over OTLP. UDP is refused, because it loses entries silently.

From 0.31, every image and Helm chart is signed keyless with cosign by the release workflow, with SLSA provenance, an SBOM and a GitHub attestation, so you can check what you run.

An app user who calls with their own Authorization: Bearer token from your identity provider instead of a shared key, and is mapped to a role.

The check that lets only single SELECT, WITH, SHOW, DESCRIBE and EXPLAIN statements through by default, before anything reaches the database.

Where QueryAPIGate keeps its own state: saved queries, keys, roles, history and the audit log. A SQLite file by default, or PostgreSQL for several instances.

?stream=true: the whole result sent straight from the database cursor instead of built in memory, so an export larger than memory still downloads. CSV, TSV, NDJSON and Parquet only, and always read-only.

An MCP tool’s answer as data: structuredContent matching its outputSchema, {"rows": [...], "truncated": <bool>}, so code reads rows rather than parsing text.

Each audit entry carries a sequence number, the previous entry’s hash and its own, so a changed, removed, inserted or reordered entry breaks every hash after it. With QUERYAPIGATE_AUDIT_KEY, someone without the key can’t re-sign an edit.

The older {name} form in saved SQL, substituted as text, so its value may only be a number, a boolean or a plain string. Bound :name parameters are preferred.

The documented account of what is at risk, who might attack it and from where, the control for each, and what QueryAPIGate does not defend against.

The database types with every feature, tested against a real server in CI and covered by the compatibility promise.

OpenTelemetry spans sent over OTLP to Jaeger, Tempo, Honeycomb, Datadog and others, showing where a request’s time went. Install the otel extra and set OTEL_EXPORTER_OTLP_ENDPOINT.

The Trino engine, which federates Hive, Iceberg, Delta, Kafka and other databases, as one governed source, with masking, the schema browser, the query time limit and catalog-qualified table grants.

For an incremental export, the largest value of a column it last delivered, bound to :since on the next run so only what changed is sent. It moves only once the file is written, so a failed run is sent again.

An experimental way to run several teams on one server, each with its own connections, queries, keys, roles, history and audit entries. Every route also answers at /w/<workspace>/….

allowed_write_ops: narrowing a key that may write to specific operations, such as only INSERT, or only on one curated query.