Trino and Starburst
How to connect a Trino cluster for read-only SQL: open-source Trino, Starburst Enterprise or Starburst Galaxy. Each person signs in with their own identity, so the cluster's own access control decides what every query and schema lookup can see.
Status: Pilot. New or partial, offered to pilot customers. Built against Trino's documented client protocol and covered by automated tests against a simulated cluster; not yet used with a customer's live cluster.
At a glance
| Connects through | Sign-in | Network | Status | First test question | |
|---|---|---|---|---|---|
| Trino and Starburst | Trino client REST API over HTTPS | Personal sign-in | Allow SourceLace's IP addresses | Pilot | "Which tables can I see in trino:prod?" |
Add each source with the usual steps. The network answers are explained in What your network needs. If the first test question fails, the error message tells you what to fix: look it up under When something goes wrong below.
What people can do
search_schemalists tables and views the person can see, ascatalog.schema.table. Without a default catalog, SourceLace looks in the first 10 catalogs (notsystem).describe_objectlists a table's columns, types and comments.query(languagesql) takes oneSELECTorWITH ... SELECTstatement in Trino SQL. Anything that could change data (INSERT,UPDATE,DELETE,MERGE,CREATE,DROP,ALTER,CALL,SET SESSIONand so on), anything with more than one statement, and table functions (TABLE(...), which in some catalogs pass raw text to the database behind them) are refused before anything is sent.- An ordinary result holds 2,000 rows (50 shown at a time); a larger answer is kept whole, up to 250,000 rows, in SourceLace's short-lived encrypted engine. SourceLace stops reading once it has enough and cancels the rest of the query on the cluster. Results are held for at most 30 minutes and never written to a database (see How long things are kept).
- These sources never accept changes.
get_recordis not used: people query with aWHEREclause. - SourceLace never uses a shared service account for these sources.
Cost and time limits
Every query goes through these steps:
- Estimate first. SourceLace asks Trino for
EXPLAIN (TYPE IO, FORMAT JSON)of the query, which plans it without running it. If Trino estimates the query would read more than the source'smax_scan_bytes(10 GB unless set), it is refused with the estimate, and nothing runs. Catalogs without table statistics give no estimate; those queries run, still capped by step 2. - Limits the cluster enforces. Each query is sent with the session properties
query_max_run_time(your organization's query time limit, about a minute unless changed on the Limits page) andquery_max_scan_physical_bytes(max_scan_bytes), so Trino itself stops a query that runs too long or reads too much. - Cancel on time-out. If the time limit passes, SourceLace also cancels the query on the cluster.
Every query carries the client tag sourcelace and the source name sourcelace, so your Trino admin can see SourceLace's queries in the query history and, if they like, give them their own resource group.
How people sign in
The source's auth option picks one of two ways. Both are per person.
auth |
How each person signs in | Good for |
|---|---|---|
password (default) |
Types their own Trino username and password into SourceLace's sign-in form. SourceLace sends it only over HTTPS and keeps it encrypted. On Starburst Galaxy the username is their email and role, such as ann@corvanta.com/analyst. |
Trino or Starburst Enterprise with password (file or LDAP) authentication; Galaxy users with a Galaxy password |
oauth |
Signs in on your identity provider's page (or Galaxy's), through an OAuth client your admin registers. SourceLace sends the access token to Trino, which takes the user from it. | Trino or Starburst Enterprise with OAuth 2.0 or JWT authentication; Galaxy with an OAuth client, including SSO users |
The redirect URL for an OAuth client is:
https://mcp.sourcelace.ai/connect/callback
What your admin does in Trino or Starburst
Once per cluster. 5 minutes for password sign-in; about 20 minutes for OAuth.
Who: the Trino or Starburst cluster admin (configuration and access control), plus your identity provider's admin for OAuth (for Microsoft Entra ID, an Application Administrator), or a Starburst Galaxy account admin.
Before you start, write down the cluster's HTTPS address. On Starburst Galaxy, it is under Clusters → the cluster → Connection info, such as corvanta-reporting.trino.galaxy.starburst.io. The Galaxy account address (corvanta.galaxy.starburst.io) is only for the Galaxy web app and is refused as host.
- The cluster must be reachable from SourceLace over HTTPS with a certificate from a public certificate authority (Galaxy always is). SourceLace does not accept a certificate from your own private certificate authority: if the cluster uses one, put it behind a load balancer with a public certificate. Allow SourceLace's outbound IP addresses in any firewall; ask support@sourcelace.com for the current list.
- Behind a proxy or load balancer that ends HTTPS in front of the coordinator: set
http-server.process-forwarded=truein the coordinator'sconfig.propertiesand restart it, so the addresses Trino hands back for the next page of results use the cluster's public address. Without it, people see "... sent an unexpected next address ...". - Password sign-in: nothing more. Each person uses the login they already have.
- OAuth with Trino or Starburst Enterprise: register SourceLace as an OAuth client in the identity provider the cluster trusts: a public client with PKCE (no secret), or a confidential client, with the redirect URL above. Its access tokens must be ones Trino accepts: the audience must be the cluster's own client id or listed in
http-server.authentication.oauth2.additional-audiences(orhttp-server.authentication.jwt.required-audiencefor JWT authentication), and the token's user field (principal-field) must name the Trino user. - OAuth with Starburst Galaxy: in Galaxy, Access control → OAuth clients → Create new OAuth client. Choose Public (SourceLace uses PKCE) and Custom, enter a client ID and the redirect URL above. Galaxy's sign-in addresses are
https://<account>.galaxy.starburst.io/oauth/v2/authorizeandhttps://<account>.galaxy.starburst.io/oauth/v2/token. - OAuth with Microsoft Entra ID: register SourceLace in the Entra admin center → App registrations as a Web app with the redirect URL above, give it the delegated permission to Trino's own app registration (API permissions → My APIs), and set the source's
scopetoapi://<Trino's app id>/.default offline_access. With the default scope, Entra gives a token for Microsoft Graph, which Trino refuses. - If your access control limits which session properties people may set, allow
query_max_run_timeandquery_max_scan_physical_bytes, or set the source's Send time and size limits to Off.
Check that it worked: after your SourceLace admin adds the source, one person clicks Connect, signs in, and asks "Which tables can I see?". Trino's query history shows the query with the client tag sourcelace.
Trino's own guide: Trino documentation (search for "OAuth 2.0 authentication" and "Session properties"); Starburst's: Starburst documentation.
Add the source (SourceLace admin)
Kind: Trino and Starburst (trino).
| Option | Type | Default | Example | What it is |
|---|---|---|---|---|
host |
Text | (required) | trino.corvanta.com, trino.corvanta.com:8443, corvanta-reporting.trino.galaxy.starburst.io |
The cluster's HTTPS address. Only HTTPS. On Galaxy, the cluster's host, not the account's. |
auth |
password or oauth |
password |
oauth |
How people sign in (see above). |
authorize_url |
Address | (required with oauth) | https://corvanta.galaxy.starburst.io/oauth/v2/authorize |
The OAuth client's sign-in page. |
token_url |
Address | (required with oauth) | https://corvanta.galaxy.starburst.io/oauth/v2/token |
Where SourceLace turns the sign-in into a token. |
client_id |
Text | (required with oauth) | sourcelace-trino |
The OAuth client's id. |
client_secret |
Secret | (none: a public client) | Only for a confidential client. Stored encrypted and never shown again. | |
scope |
Text | openid offline_access |
api://trino/.default offline_access |
The scopes to ask for, so the token is one the cluster accepts. With Microsoft Entra ID, Trino's app scope is required. |
catalog |
Name | (none) | hive |
Default catalog. With it, search_schema looks only there. |
schema |
Name | (none) | sales |
Default schema. |
role |
Name | each person's default | analyst |
A system role to use for queries. |
max_scan_bytes |
Number of bytes | 10000000000 (10 GB) |
50000000000 |
The most one query may read. |
session_limits (Send time and size limits) |
On or Off | On | Off | Send the time and size limits as session properties. Off only if the cluster refuses them. |
When something goes wrong
| What you see | What it means | What to do |
|---|---|---|
| "... is your Starburst Galaxy account's address ..." | host is the Galaxy account, not a cluster. |
Copy the cluster's host (see Before you start). |
| "The Trino host option must be the cluster's HTTPS address ..." | host is not an HTTPS address, or has a path. |
Use the cluster's address, such as trino.corvanta.com:8443. |
| "... did not accept that username and password." | The login is wrong. | Use your own Trino login. On Galaxy, your email and role, such as ann@corvanta.com/analyst. |
| "... did not accept the token from your identity provider: its audience must be one Trino accepts ..." | The token is for another audience (with Entra ID, Microsoft Graph). | Set scope to Trino's app scope, or add the audience to additional-audiences. |
| "Sign-in was not completed: ... redirect_uri ..." | The OAuth client's redirect URL differs. | Set it to the redirect URL above. |
| "Trino estimates this query would read about ..., more than this source's limit of ..." | The query would read too much. | Select fewer columns or filter on partition columns, or raise max_scan_bytes. |
| "... took too long to run this query, so it was stopped." | The time limit passed. | Narrow the query. |
| "Trino says you do not have access (...)" | Trino's access control refused it. | Query a table you can read, or ask your Trino admin. |
| "... does not let SourceLace set its query time and size limits ..." or "... does not accept SourceLace's query time and size limits ..." | The cluster refuses the two session properties, or does not know them (an older release, or Galaxy). | Allow them, or set Send time and size limits to Off. |
| "... sent an unexpected next address, so SourceLace stopped reading." | The cluster is behind a proxy or load balancer and hands back its own internal address for the next page of results. | Ask your Trino admin to set http-server.process-forwarded=true on the coordinator (see the admin steps above). |
| "... is a private network address ..." | host is a private address. |
Use the cluster's public address. |
| "... could not be reached." | The address is wrong, or a firewall blocks SourceLace. | Check host, and allow SourceLace's IP addresses. |
| "Table functions (TABLE(...)) are not allowed ..." | Table functions are refused. | Query the tables directly. |
| "... no longer accepts your sign-in." | The sign-in ended. | Connect again. |
| "Set the ... host option: the cluster's address ..." or "The ... auth option is password (the default) or oauth." | The host is empty, or auth is neither password nor oauth. | An admin fixes the option named. |
| "Set the ... option: the address from your identity provider or Galaxy ..." or "The ... option must be an https:// address ..." | The OAuth address is missing or not https://. | An admin enters it from the identity provider or Galaxy. |
| "The ... scope option must be scope names separated by spaces ..." or "The ... role option must be a plain role name such as analyst." or "The ... catalog option must be a plain name such as sales." (or schema) | The option holds something other than plain names. | An admin corrects it. |
| "The ... max_scan_bytes option must be a number of bytes ..." or "The ... session_limits option is on (the default) or off." | The option has an invalid value. | An admin enters plain digits, or on or off. |
| "... stopped this query because it read more than the source's limit." | The query would read more data than the source allows. | Select fewer columns or filter on partition columns. |
| "...: .... Call search_schema and describe_object for the right names." or "... has no table or view ... that you can read." | A catalog, schema, table or column name is wrong, or you may not see it. | Use names from search_schema and describe_object. |
| "... refused the query: .... Fix the query and try again." | Trino said the query is wrong. | Fix what Trino names. |
| "... does not have the resources for this query right now (...)." | The cluster is busy or short of memory. | Narrow the query, or try again later. |
| "... could not run the query: .... Try again; if it keeps happening, ask your Trino admin." | Trino failed for a reason of its own. | Try again; then ask your Trino admin. |
| "... refused SourceLace's request (HTTP 403)." or "... is not available right now (HTTP ...)." or "... returned HTTP .... Check the source's host option." | The cluster refused, is down, or the host is wrong. | Check your access, wait and try again, or check the host option. |
| "SourceLace refused to call an unexpected address for ...." or "... did not answer in time. Try again shortly." | A link pointed outside the cluster, or the cluster was slow. | Try again. If it repeats, contact support. |