SQL connectivity

Personal access tokens

Every SQL connection authenticates with a personal access token (PAT) used as the password. Mint and manage yours in the product UI:

1. Open Settings → Personal access tokens (/settings/tokens).
2. Enter a name (e.g. DBeaver), an optional expiry in days, and pick scopes — for SQL clients, read:sql is enough. Leaving every scope unchecked mints a full-access token; grant only what the client needs.
3. Click Create token. The secret (vflh_…) is shown exactly once — copy it immediately. Reloading the page removes it from view permanently, on the server as well as in the UI.
4. The same page lists your tokens with prefix, state, and last-used time, and offers Rotate (new secret, old one dies immediately) and Revoke.

Your token is a password on these endpoints — treat it like one. The planes require TLS, so it never crosses the wire in the clear.

Your client will log it if you let it. DBeaver, DataGrip, beeline, and most JDBC tooling print the full connection string — password included, in cleartext — at DEBUG or TRACE level, and those logs land in a workspace directory, a CI artifact, or a pasted bug report. This has already happened to us once. Keep SQL clients at their default log level while connecting; if a token has appeared in a log, in a screenshot, or in a chat message, treat it as exposed and rotate or revoke it on /settings/tokens (Rotate mints a new secret and kills the old one immediately) rather than deciding who might have read it.

Subject format caveat (Hive plane) — #2011: a token’s subject is the identity it belongs to. Tokens minted in the UI are bound to your sign-in email, but the Hive/Thrift plane cannot currently authenticate subjects containing @ (the email is truncated at the @). Until the identity unification in #2011 lands, the Hive plane needs a token bound to a no-@ subject (e.g. jane-doe rather than jane.doe@example.org) — ask your platform administrator to provision one. The pg-wire plane is unaffected: email subjects work there as-is.

Hive / Thrift-HTTP plane (Databricks parity)

The Spark SQL gateway speaks HiveServer2 Thrift — the same protocol shape as a Databricks SQL warehouse, so any tool with a Databricks/Hive connector works. Each user gets an isolated Spark engine; SQL runs with full Spark semantics over the Iceberg medallion.

PostgreSQL wire-protocol plane (pg-wire)

The lakehouse also answers the PostgreSQL wire protocol directly — no Spark warm-up, sub-second answers for lookups, and compatibility with the enormous Postgres client ecosystem. Each lakehouse catalog appears as a Postgres database; your tenant comes from the token, never from anything you type.

Superset (BI dashboards) via SSO

Apache Superset is available for dashboarding without any driver setup — it connects to the SQL planes server-side, and you sign in with your existing platform account:

Known limitations (current)

These are real, open issues a connecting user can hit today. Each links to its tracker: