Configuration

All configuration is environment variables (.env locally, container environment in Docker). .env.example in the repository documents the full set; this page explains the ones you’ll actually change.

QueryProxy settings

retry_after is derived: unless you set DB_QUEUE_RETRY_AFTER (or the Beanstalkd / Redis equivalent) yourself, it is QUERYPROXY_EXECUTION_TIMEOUT

• 30 seconds (330 for the default 300). The Docker entrypoint derives the worker --timeout (execution timeout + 10) and stopwaitsecs (execution timeout + 20) from the same setting. If you set retry_after explicitly, keep it above the execution timeout, because the query job is stopped at that point; the default +30 leaves a margin. A value at or below it lets a slow query be re-reserved while it is still running and then marked failed, even though its write may commit, and logs a warning when queue:work (daemon or --once) or queue:listen starts. A fixed *_QUEUE_RETRY_AFTER=330 left over from the 0.2.0 .env.example stops the derivation, so remove it unless you set it on purpose.

A TOTP code accepted for QUERYPROXY_REQUIRE_2FA is burned, so it cannot be replayed for the rest of its window. One practical consequence: signing in on a second device within the same 30-second step means waiting for the next code.

QUERYPROXY_EXTRA_UNTRUSTED_LANGUAGES and QUERYPROXY_EXTRA_DANGEROUS_VARIABLES add to the two lists the SQL guards judge CREATE EXTENSION and SET by. They can only extend: the built-in entries are the floor, merged back on top of whatever the environment provides, so a trimmed list cannot disarm the guard.

MySQL / MariaDB targets: sql_mode

The guard reads quotes and backslashes the default way, so a request is refused when the session sql_mode would read them differently. Before it runs the SQL on a mysql or mariadb connection, QueryProxy reads @@SESSION.sql_mode; if it contains NO_BACKSLASH_ESCAPES or ANSI_QUOTES, the request fails and nothing runs, with a message naming the flag. QueryProxy itself sets a strict sql_mode when it connects, which replaces the server’s default, so if this fires, look for what changes the mode after connect (a proxy in between, a changed connection configuration); keeping the flags out of the server and connection-user defaults is still sensible, but on its own it will not clear it. Submitting a SET that changes sql_mode is refused on every driver (see SQL guards).

Read credentials and timeouts

A read request runs in a read-only session on the target database, with a statement timeout and a lock timeout that QueryProxy sets. What that means per driver:

The statement timeout is QUERYPROXY_EXECUTION_TIMEOUT minus 5 seconds (at least 1), and the lock timeout is QUERYPROXY_LOCK_TIMEOUT. Writes get the same limits. On MySQL the statement timeout does not apply to writes, so a long write there is not cut by the database; the job ends at the execution timeout and the write may still run on the server. Stop query cancels it earlier.

MySQL and MariaDB set the read-only mode for the whole session, so a statement that commits implicitly cannot slip out of it. On PostgreSQL, SELECT … FOR UPDATE and FOR SHARE are refused inside a read request.

A connection can carry an optional read username and password (encrypted like the main credentials). Reads use them; writes never do. The connection test tries both, and a failure of the read credentials starts with “Read credentials:”. Give the read user SELECT privileges only. On SQL Server this is the only database-side protection for reads, because the engine has no read-only session; ApplicationIntent=ReadOnly does not protect against writes. SQLite connections do not store a read identity.

TLS to target databases

Each network connection has a TLS setting in the connection form. New connections default to required TLS: they fail instead of falling back to plain text.

For PostgreSQL, MySQL and MariaDB you can paste a CA certificate, a client certificate and a client key as PEM. They are stored encrypted, written at run time to storage/app/tls/<connection id>/ (directory mode 0700, files 0600) and removed with the connection. The form never sends them back to the browser, and the client key must not be password protected. The SQL Server form has no PEM fields.

require and required without verification encrypt the traffic but do not prove who answers, so they do not stop a man in the middle. Turn verification on where the network is not fully yours.

Connections that exist from before v0.3.0 keep their old behaviour and are marked “TLS not enforced” (PostgreSQL, sslmode=prefer) or “TLS: driver default” in the list; queryproxy:doctor names them. SQL Server requires the pdo_sqlsrv extension for required TLS: without it Laravel would silently fall back to a connection that ignores the encryption setting, so QueryProxy refuses to connect. With Encrypt=true, refusing a server that offers no encryption is the ODBC driver’s documented behaviour; QueryProxy’s tests cannot simulate such a server.

Secrets from files

Docker and Kubernetes secrets arrive as files. For each variable below, set the same name with a _FILE suffix instead, and the entrypoint (and the application) read the value from that file:

services:
  app:
    environment:
      APP_KEY_FILE: /run/secrets/queryproxy_app_key
      DB_PASSWORD_FILE: /run/secrets/queryproxy_db_password
      QUERYPROXY_METRICS_TOKEN_FILE: /run/secrets/queryproxy_metrics_token
    secrets: [queryproxy_app_key, queryproxy_db_password, queryproxy_metrics_token]

In Kubernetes, point the _FILE variable at the path where a Secret volume is mounted.

• Setting both X and X_FILE is an error and the container does not start. A plain variable set to null, (null) or (empty) counts as unset.
• The file must exist, be readable and not be empty. Trailing line breaks are removed; everything else is kept.
• Error messages name the variable and the path, never the value.
• php artisan config:cache (the image runs it on every start) writes the resolved values, secrets included, in plain text to bootstrap/cache/config.php. A secret that came from a file therefore also lives in that cache file.
• The signing secrets and webhook URLs of the incoming-webhook mode of Slack and Teams are not environment variables; they are stored encrypted in the application database. The Slack app’s own credentials (QUERYPROXY_SLACK_CLIENT_SECRET, QUERYPROXY_SLACK_SIGNING_SECRET) are plain environment variables and have no _FILE form.

php artisan queryproxy:doctor reports which secrets are read from files (secret_files) and fails when one cannot be read. See Troubleshooting.

Single sign-on

Single sign-on through OpenID Connect is configured with the QUERYPROXY_OIDC_* variables in the table above. Register {APP_URL}/auth/oidc/callback as the redirect URI at the provider. The provider examples, the role map and the rules for creating and linking accounts are on Single sign-on. The client secret can come from a file (QUERYPROXY_OIDC_CLIENT_SECRET_FILE), like the other secrets in Secrets from files.

Schema explorer

The Query Studio’s schema panel and name completion read the target database’s catalog through fixed queries, in a read-only session, without an approval. Only users who may use the connection can read it, and the answer lists tables, views and columns, never data.

• QUERYPROXY_SCHEMA_TIMEOUT is the statement timeout of that read, in seconds. It is separate from the execution timeout of requests. A read also needs a free connection slot (QUERYPROXY_CONNECTION_SLOTS); with every slot busy the panel asks the user to try again shortly.
• The result is cached per connection for QUERYPROXY_SCHEMA_CACHE_TTL seconds, and editing the connection starts a fresh entry. A manual Refresh skips the cache and is limited per user and connection to QUERYPROXY_SCHEMA_REFRESH_LIMIT a minute. The cache holds names and types only; the lock on masked columns is computed from the current masking rules on every answer.
• QUERYPROXY_SCHEMA_MAX_COLUMNS caps one read. A larger schema is cut at a table boundary with the default schema listed first, and the panel says it is truncated.
• On MySQL and MariaDB only the connection’s own database is listed. The system schemas (information_schema, mysql, performance_schema, sys) are never listed.
• Each read from the database is recorded as schema.read in the audit log, with the object and column counts. A read served from the cache is not.

Application key and HTTPS

APP_KEY encrypts your stored connection credentials and chat secrets. For production, set it explicitly and keep it stable — a regenerated key (e.g. on container recreation) makes every stored credential unreadable. Generate one with php artisan key:generate --show, and when rotating, move the old key into APP_PREVIOUS_KEYS (comma-separated) so existing ciphertext still decrypts.

When serving over HTTPS behind a reverse proxy, set SESSION_SECURE_COOKIE=true.

Behind a reverse proxy

Breaking change — set TRUSTED_PROXIES when a proxy sits in front of QueryProxy. Earlier versions trusted every proxy. From this version no proxy is trusted by default, and until you name yours the app reads the connecting peer as the client.

TRUSTED_PROXIES takes a comma-separated list of the IPs or CIDRs allowed to set X-Forwarded-* headers:

TRUSTED_PROXIES=10.0.0.0/8

Until that list names your proxy, X-Forwarded-Proto is ignored — HTTPS is not detected, so no HSTS header is sent — and audit entries record the proxy’s address instead of the client’s.

Never set it to *. Trusting every proxy lets any client send its own X-Forwarded-For, which forges the client IP in the audit trail and hands out unlimited login and 2FA attempts, because both throttles are keyed per IP.

X-Forwarded-Host is not honoured at all, whatever the list says: a forged host header rewrote the link in password-reset mail. As a second layer, the request host is pinned to APP_URL’s host (and its www. sibling), so absolute URLs — signed routes, password-reset mails — always point at your own installation. Set APP_URL to the address users actually reach.

If the installation answers to more than one name, list the others in TRUSTED_HOSTS:

TRUSTED_HOSTS=queryproxy.internal,db.example.com

That is the supported way to run a multi-domain deployment now that X-Forwarded-Host is ignored — a hostname you have not listed still cannot rewrite a password-reset link. The names are added to APP_URL’s host (and its www. sibling), never replace it. Entries that do not parse as a hostname are dropped silently, so a typo cannot take the installation down.

Both values are read through the application config, so setting them in .env is enough. If you cache the configuration, re-run php artisan config:cache after changing them; the Docker image re-caches on every start.

Application database

QueryProxy’s own data (users, teams, requests, audit log) lives in SQLite by default — zero configuration. For MySQL, MariaDB, PostgreSQL or SQL Server, set the standard Laravel variables:

DB_CONNECTION=pgsql        # or mysql, mariadb, sqlsrv
DB_HOST=db
DB_PORT=5432
DB_DATABASE=queryproxy
DB_USERNAME=queryproxy
DB_PASSWORD=change-me

This is the application database — the databases you proxy are configured in the UI under Connections, per team, with encrypted credentials.

Moving from SQLite to another database. Stop QueryProxy, then run php artisan queryproxy:migrate-appdb --to=<dsn>, for example --to=pgsql://user:password@host:5432/queryproxy (URL-encode special characters in the password). It runs the migrations on the target, copies every table in foreign key order, compares the row count of every table and runs audit:verify on the target. The audit triggers stay in place and the audit hashes and the chain head are copied unchanged. The target must be empty (a database that was only migrated is fine). --dry-run checks everything and writes nothing; without --force the command asks you to confirm that QueryProxy is stopped. The copy is one transaction, so a failure leaves a migrated, empty target you can retry. The cache tables are not copied, and the target password is never printed. Afterwards switch DB_CONNECTION and the other DB_* settings and start QueryProxy again.

SQL Server as the application database. Use the mssql image variant: the default image has no pdo_sqlsrv (see SQL Server targets). Move an installation there with php artisan queryproxy:migrate-appdb --to="sqlsrv://user:password@host:1433/queryproxy?trust_server_certificate=true". Options in the query string, such as trust_server_certificate and encrypt, go to the connection of that command only. The application has no separate DB_* variable for them, so after the move give it the same DSN, with the same options, in DB_URL; otherwise a server with a self-signed certificate is reachable for migrate-appdb but not for the running application. DB_URL carries the password, so URL-encode special characters in it and keep it as secret as DB_PASSWORD. SQL Server refuses foreign keys that give a table more than one cascade path, and the schema has several. So on SQL Server only, eight foreign keys are created with ON DELETE NO ACTION: query_requests.team_id, masking_rules.team_id, connection_grant_requests.team_id, connections.created_by, connection_user.granted_by, connection_grant_requests.decided_by, and the two query_requests keys to users (user_id and reviewed_by), which are RESTRICT on every driver, so that request history is never deleted with a user (ADR-018). QueryProxy does what the database would have done on a delete: deleting a team removes its requests, masking rules and grant requests first, and hard-deleting a user who has no requests sets the keys that referenced them to NULL.

What differs is raw SQL that deletes a team or a user. On SQL Server it is refused only while rows still point at the team or user through one of those eight keys: for a team, requests, masking rules or grant requests; for a user, connections it created, grants it gave, grant requests it decided, or requests it filed or reviewed. For the six keys that cascade or set NULL on the other drivers, the delete is refused on SQL Server instead. The two request keys to users are refused on every driver. Nothing changes on PostgreSQL, MySQL, MariaDB or SQLite: no new migration, no change to an existing installation, the same delete results.

Tested versions. Target databases: PostgreSQL 17, MySQL 8.4, MariaDB 11.4 and 11.8, SQL Server 2022 and SQLite. Application database: SQLite, MySQL 8.4, MariaDB 11.4 and 11.8, PostgreSQL 17, and SQL Server 2022 (the mssql image variant). PostgreSQL-compatible target databases: CockroachDB v25.4 and YugabyteDB 2025.2, each with known differences listed on PostgreSQL-compatible databases, which includes what the SQL guard does not cover on CockroachDB. Other versions may work but are not tested.

Queue

The queue is database-backed by default (no Redis required). To move it to Redis:

QUEUE_CONNECTION=redis
REDIS_HOST=redis

REDIS_QUEUE_RETRY_AFTER is optional: when unset it is derived from QUERYPROXY_EXECUTION_TIMEOUT + 30 seconds (see the note under the settings table). Only set it to override that value, and keep it above the execution timeout.

The worker command stays the same. Keep its --timeout a little above the execution timeout (execution timeout + 10 seconds; QUERYPROXY_EXECUTION_TIMEOUT is 300 by default, hence 310):

php artisan queue:work --queue=queries,default --tries=1 --timeout=310

In a manual setup this number is not derived for you: if you change QUERYPROXY_EXECUTION_TIMEOUT, change --timeout to match (the Docker entrypoint derives it itself).

The same warning (retry_after at or below the execution timeout) is logged once when queue:listen or queue:work --once starts, not only for a daemon queue:work. The short-lived queue:work --once processes that queue:listen spawns do not repeat it.

In the repository’s docker-compose.yml, the separate worker example no longer hard-codes --timeout=310: it passes QUERYPROXY_WORKER_TIMEOUT, which the image entrypoint derives as QUERYPROXY_EXECUTION_TIMEOUT + 10. Set QUERYPROXY_EXECUTION_TIMEOUT on that service and the worker follows. This needs the image’s default entrypoint, so do not override entrypoint: on the worker service.

Result storage on S3

Set QUERYPROXY_RESULT_DISK=s3 and the standard AWS_* variables. Result files are written as NDJSON, streamed — memory use stays flat regardless of result size.

The disk must be private. Result paths are predictable (results/{team_id}/{id}.ndjson), so a publicly served disk would hand out every team’s rows straight from the web root, bypassing the download authorization entirely. QueryProxy therefore refuses to write results when QUERYPROXY_RESULT_DISK points at the public disk or at any disk configured with visibility => public, and the request fails with an explicit message instead.

SQL Server targets

The default Docker image ships pdo_pgsql, pdo_mysql and pdo_sqlite. For Microsoft SQL Server targets use the mssql image variant: queryproxy/queryproxy:<version>-mssql, or queryproxy/queryproxy:mssql for the latest stable release. It adds Microsoft’s ODBC Driver 18 and the pdo_sqlsrv extension, is built for linux/amd64 and linux/arm64, and is scanned, signed and attested like the default image. :mssql moves only with stable releases and never takes latest. Microsoft’s driver is under Microsoft’s own licence (https://aka.ms/odbc18eula); using the variant means accepting it.

To build the variant yourself, pass --build-arg INSTALL_SQLSRV=1 to the repository’s Dockerfile. The extensions have to be present in the PHP build that runs both the web process and the queue worker, because approved queries execute on the worker: run the same variant for every role.

Privileges for Stop query

Stop query cancels the running statement from a second connection. It needs no extra privilege on PostgreSQL, MySQL and MariaDB beyond what the connection’s user has (pg_signal_backend or CONNECTION_ADMIN suffice for other users’ sessions). On SQL Server the connection’s login needs:

• VIEW SERVER STATE: without it sys.dm_exec_sessions shows only the caller’s own session, the run cannot be found, and the request is marked cancelled without signalling the server (a warning appears and the statement ends at its timeout).
• ALTER ANY CONNECTION: KILL <spid> needs it.

On SQL Server, Stop ends the session, so an open transaction rolls back on the server; on the other drivers only the statement is cancelled. The button is not shown for SQLite.

After a statement has started, QueryProxy does not reconnect on a network drop; the run fails instead of continuing on a new session.