Our engine never sees your warehouse password
datahashi

Query Runner

The process that runs compiled SQL on your warehouse. It holds the password, the kill switch, and the audit log.

Updated

Query Runner is a process that you install next to your warehouse. It runs SQL that the engine sends. The engine compiles the Semantic Query into SQL. It then sends that SQL to Query Runner over HTTP.

Query Runner holds the warehouse password. It is the only component that opens a network connection to your warehouse.

flowchart TD
    C["AI agents · BI · applications"] -->|"Semantic Query<br/>metrics, dimensions, filters"| E["datahashi engine<br/>resolve join graph → apply data roles → compile dialect SQL"]
    E -->|"POST /v1/sql { sql, args }<br/>runner bearer token"| R["Query Runner<br/>holds DSN · table/field policy · kill switch · audit"]
    R -->|"local native connection"| W[("Your warehouse<br/>Postgres · MySQL · Snowflake · BigQuery · and five more")]

The split of jobs is strict:

  • The engine resolves the model, applies business logic, compiles SQL, and applies data roles.
  • The runner holds the password, runs SQL, and writes the audit log.

Four guarantees

1. The engine never holds the password

You set the DSN, password, or IAM key in the runner config or in environment variables. Credentials never go to the engine. They never go to the control plane.

2. Local kill switch

Pause or stop Query Runner. All query execution stops for every consumer. You do not revoke API keys. You do not wait on an external provider.

3. Local table policy

The runner can allow or deny tables, columns, and values per runner key. The rules live on disk. If the compiler emits SQL for a denied table, the runner blocks it. The warehouse never sees that query.

4. Local audit log

The runner writes one JSON object per request. The entry records the time, the key id, the status, the duration, and the row count. It can record the SQL text. It never records the DSN, bound values, or result cells.

Deployment modes

Mode Who operates it Where the DSN lives Network
External (recommended) You, in your private VPC Your machine only The warehouse needs no public ingress
Hosted datahashi, on dedicated runners Shared runner cluster Convenience for development or quick tests
Community loopback Child process in one container Container environment Engine and runner start together

Warehouse backends

Query Runner has a native driver for each of these engines:

  • PostgreSQL. Parameterized queries, schema read, statement timeouts, and table, field, and value policy.
  • MySQL, ClickHouse, Redshift, SQL Server, Databricks, Snowflake, BigQuery, and DuckDB. Parameterized queries and a statement gate.

Table, field, and value rules run on PostgreSQL only. Every other engine needs allow_unpoliced_backends: true on the key’s policy. That policy then allows every table the database user can read. The statement gate still rejects anything that is not one SELECT or WITH.

HTTP and admin

Query Runner exposes these endpoints:

  • POST /v1/sql: Run parameterized SQL. Return JSON or a stream.
  • POST /v1/schema: Read tables and columns. Denied objects are omitted.
  • GET /healthz: Process is up. No key. A paused runner still returns 200.
  • GET /v1/readyz and POST /v1/ping: Warehouse ping. There is no GET /v1/ping.
  • POST /admin/v1/pause and POST /admin/v1/resume: Kill switch on the admin port.
  • POST /admin/v1/reload: Reload files. A bad file keeps the previous snapshot.
  • GET /admin/v1/status and GET /admin/v1/logs: Status and recent audit records. No secrets.

Next: Rollups · Install Query Runner.