Execute each plane’s steps in order and tick the box when the observed result matches the expected one. A mismatch is a finding: note the step number, the exact error text, and check the troubleshooting table — several rough edges are known, open issues, and hitting one with the documented symptom counts as expected behavior for this round of UAT.
Client setup details (drivers, walkthrough screenshots-level steps) live in the SQL connectivity guide.
psql or DBeaver/DataGrip with pgJDBC 42.7.4 (or preferQueryMode=simple set — #2021).org.apache.hive.jdbc.HiveDriver — a MySQL or Generic JDBC profile will not work, and step 1 below has you prove that), and an admin-provisioned no-@ subject token (#2011 — UI-minted email-subject tokens cannot authenticate on this plane yet).| # | Action | Expected result | Pass |
|---|---|---|---|
| 1 | Sign in to the web app and open Settings → Personal access tokens (/settings/tokens). | The page lists your existing tokens (or an empty state) and a “Create a token” form. | |
| 2 | Create a token named uat-<date> with expiry 1 day and only the read:sql scope checked. | A one-time secret reveal appears showing a vflh_… value with a Copy button. Copy it — this is the password for every SQL step below. | |
| 3 | Reload the page. | The secret is gone and cannot be re-displayed. The token row shows its prefix, active state, scopes, and expiry. | |
| 4 | After finishing all planes below: click Revoke on the UAT token. | The row flips to revoked; any subsequent SQL connection with it is refused (SQLSTATE 28000). |
| Symptom | Cause | Fix | Issue |
|---|---|---|---|
Hive plane connects, then the tree is empty/broken and the log shows SELECT SCHEMA_NAME FROM information_schema.schemata failing | the client is on a MySQL or Generic JDBC driver profile, which discovers schemas through information_schema. Spark SQL has none and never will | switch to the Apache Hive driver profile (org.apache.hive.jdbc.HiveDriver); schema discovery then goes through Thrift metadata (SHOW DATABASES, SHOW NAMESPACES) | — |
Hive plane: SHOW DATABASES returns nothing, so the deployment looks like it has no data | the session is on Spark’s built-in spark_catalog, which is empty — either no catalog fragment on the URL, or one copied from a dbt profile | pin #spark.sql.defaultCatalog=lakehouse. spark_catalog is the dbt-only workaround (PyHive issues USE default on connect — #1564) and must not be copied into a human or BI client | #2018 |
| Your token appeared in a client log, a screenshot, or a pasted stack trace | JDBC tools print the whole connection string, password included, at DEBUG/TRACE level | treat it as exposed: Rotate or Revoke on /settings/tokens, then reconnect with the new secret. Keep SQL clients at default log level | — |
| pgJDBC: “Something unusual has occurred…” / cannot connect at all, or “Error operating ExecuteStatement” on every statement | the pg-wire extended query protocol is broken; stock pgJDBC uses it by default | pin pgJDBC 42.7.4 exactly, or add preferQueryMode=simple to the URL | #2021 |
| DBeaver/DataGrip/VS Code crashes while expanding the database tree | events/partners catalogs project empty-string schema/table names | limit displayed databases to your catalog; do not expand events/partners | #2025 |
| Connection succeeds but the catalog tree is empty / every SELECT is refused (42501) | the subject has no read grants — ReBAC filters the estate to what you may read | admin: POST /api/v1/admin/authz/grant (viewer on the catalog) then POST /api/v1/admin/authz/backfill-parents to cascade it | #2018 |
| Hive plane refuses your login even though the token works on pg-wire | email subjects are truncated at @ on the Thrift plane | use an admin-provisioned token bound to a no-@ subject | #2011 |
Hive plane: SHOW DATABASES empty or lands in the wrong catalog; unqualified table names not found | tenant subjects do not yet default into their tenant namespace | add #spark.sql.defaultCatalog=lakehouse to the JDBC URL and use lakehouse.tenant_<t>.… fully-qualified names | #2018 |
| First Hive query hangs ~a minute, client may print a warm-up/engine line | your dedicated Spark engine is cold-starting | wait — it completes and subsequent queries are fast; do not cancel | — |
SQLSTATE 28000 at connect | bad, expired, or revoked token — or the client skipped TLS | re-check the token in /settings/tokens; ensure sslmode=require | — |
SQLSTATE 25006 on CREATE/INSERT/UPDATE | the pg-wire endpoint is read-only by design | expected — writes go through the platform APIs, not this plane | — |
| Superset panels show a connection-limit error on first paint | dashboard fan-out is throttled to protect the shared SQL gateway | refresh — panels render in waves | — |