PostgreSQL wire protocol

When ENGINE_SQL_ADDR is set, datahashi listens with the PostgreSQL wire protocol (v3). TLS is mandatory. BI tools, SQL IDEs, and reporting engines connect with a generic PostgreSQL JDBC or ODBC driver.

The engine turns incoming SQL into a Semantic Query. Raw client SQL never reaches your warehouse.

flowchart TD
    BI["BI tools<br/>Metabase · Superset · Tableau · Power BI"] -->|"PostgreSQL wire, TLS, port 5432<br/>SELECT region, avg_order_value FROM Order"| W
    subgraph W["datahashi sqlwire engine"]
        direction TB
        W1["1 · Parse bounded SELECT grammar"] --> W2["2 · Translate to a structured Semantic Query"]
        W2 --> W3["3 · Resolve Join Graph, apply Data Roles and RLS"]
        W3 --> W4["4 · Route to DuckDB rollups or compile warehouse SQL"]
    end
    W -->|"parameterized SQL over HTTP"| R["Query Runner"]

The security rule is strict:

• The engine does not run the client’s raw SQL on your warehouse.
• It parses SELECT statements into Semantic Queries. REST and MCP use the same grants and row filters.

Why a bounded SELECT grammar?

BI tools query tables with aggregations and grouping. Free-form SQL would break the semantic layer:

• Users could write wrong joins.
• Queries could skip metric definitions.
• Callers could use dialect-specific injection.

datahashi accepts a bounded subset of SQL:

• SELECT <metrics, dimensions, or measures> FROM <entity>
• WHERE <filters>
• GROUP BY <dimensions>
• ORDER BY <selected column>
• LIMIT <n> OFFSET <m>

FROM names one entity. It is not the model name. A metric is a column on every entity table, because a metric is not owned by one entity. There is no HAVING clause on this wire. A hand-written join, subquery, CTE, or window function is a syntax error.

The engine turns this syntax into a Semantic Query. It resolves join paths. It checks grants. It compiles warehouse SQL.

Authentication

In datahashi Cloud

The console creates SQL credentials under Governance → SQL / JDBC / ODBC:

• Username. Fixed identifier for the principal.
• Password. Generated secret. A credential issued with SCRAM support logs in by SCRAM-SHA-256; an older one logs in by a password sent inside TLS until you rotate it.
• Data roles. Entitlements on the credential.
• Revocation. Remove the credential in the console. The next query from that client fails.

In the community engine

SQL wire clients authenticate with the same Bearer token as REST:

• Host. Your engine host (for example localhost).
• Port. The port in ENGINE_SQL_ADDR (for example 5432).
• Database. Any string. It is not the model name.
• User. Any label. The engine uses it only in the audit log.
• Password. ENGINE_API_KEY or a JWT. With ENGINE_API_KEY the login is SCRAM-SHA-256.

Connect a BI tool

Use standard Postgres connection fields:

Field	Value
Driver / Type	PostgreSQL
Host	<engine-host>
Port	5432
Database	Any string. It does not select a model.
User	Any label, or the issued SQL credential username
Password	Bearer token: ENGINE_API_KEY, a JWT, or the issued SQL credential
SSL / TLS	Required. Plaintext is refused. Use sslmode=require.

After you connect, each entity is one table. Dimensions, measures, and metrics are its columns. Users can build charts without writing SQL joins.

Step-by-step setup for each tool: Connect a BI tool.

Next: Write your first model · Query the REST API.