Trino Go Client

The DSN is a URL used to connect to Trino. The format is: http[s]://user[:pass]@host[:port][?parameters]

Parameters are case-sensitive. You can use the Config.FormatDSN helper function to build a DSN from a trino.Config struct.

If your DSN includes a password (e.g., http://user:pass@host), the client automatically enables HTTP Basic authentication by setting the Authorization header.

Note: HTTP Basic authentication is only supported on encrypted connections over HTTPS.

The client supports the Trino spooling protocol, which allows efficient retrieval of large datasets by downloading segments in parallel and potentially out-of-order. The client uses json encoding by default if the server supports it.

Configuring Encodings

You can specify the encoding via sql.Named("encoding", ...) arguments. Supported encodings include json, json+lz4, and json+zstd.

You can provide a single encoding or a comma-separated list of preferred encodings.

// Single encoding
rows, err := db.Query(query, sql.Named("encoding", "json+zstd"))

// Preference list
rows, err := db.Query(query, sql.Named("encoding", "json+zstd, json+lz4, json"))

To build the client locally and run the test suite with race detection and a timeout, use the following command:

go test -v -race -timeout 2m ./...

To forward an access token via an authorization header instead of including it in the query text, follow these two steps:

1. Add a sql.NamedArg with the name accessToken (e.g., sql.Named("accessToken", "<your_token>")).
2. Set the ForwardAuthorizationHeader field to true in the trino.Config struct.

This configuration overrides the AccessToken set in the Config struct and prevents the token from being logged in Trino's query history.

You can use a custom http.Client (e.g., for custom TLS configs, proxies, or OpenTelemetry instrumentation) by registering it with trino.RegisterCustomClient and referencing it in the DSN via the custom_client parameter.

// Register the client
trino.RegisterCustomClient("foobar", foobarClient)

// Use it in the DSN
db, err := sql.Open("trino", "https://user@localhost:8080?custom_client=foobar")

To use the Trino driver in your Go application, install it using go get. Ensure you have Go 1.25.5 or newer and Trino 372 or newer installed in your environment.

go get github.com/trinodb/trino-go-client/trino

The Trino client implements the Go database/sql/driver interface. To use it, import the package with a blank identifier and use sql.Open with trino as the driver name and a valid DSN as the data source name.

import "database/sql"
import _ "github.com/trinodb/trino-go-client/trino"

dsn := "http://user@localhost:8080?catalog=default&schema=test"
db, err := sql.Open("trino", dsn)

Roles can be assigned per catalog for the session.

Via DSN: Use the roles parameter with the format catalog1:role1;catalog2:role2.

Via Query Parameters: Override DSN roles by adding a sql.NamedArg with the key X-Trino-Role containing a map[string]string of catalog-to-role assignments.

// Via Config struct (for DSN generation)
c := &Config{
	ServerURI: "https://foobar@localhost:8090",
	Roles:     map[string]string{"catalog1": "role1", "catalog2": "role2"},
}
dsn, _ := c.FormatDSN()

// Via Query parameter (overrides DSN)
sql.Named("X-Trino-Role", map[string]string{
    "catalog1": "role1",
    "catalog2": "role2",
})

To execute a query as a user different from the authenticated principal, add a sql.NamedArg with the key X-Trino-User to your query parameters. This value is used by the driver to inform Trino of the executing user but is not passed as part of the SQL query text itself.

db.Query("SELECT * FROM foobar WHERE id=?", 1, sql.Named("X-Trino-User", string("Alice")))