clients > CLI

CLI #

The Trino command line interface (CLI) provides a terminal-based, interactive shell for running queries and inspecting catalog structures in any cluster. You can connect to Starburst Galaxy, Starburst Enterprise platform (SEP), and Trino. The CLI is distributed as an executable JAR file.

Requirements #

The Trino CLI requires Java 8 or newer, installed and available through the PATH defined in your terminal. Run the java --version command to verify that a compatible Java version is installed.

Download and install #

Download the latest Trino CLI as an executable JAR file from the SEP documentation. The latest CLI version is recommended, as the CLI is backwards-compatible with older SEP versions.

The JAR file is usable as-is, but for ease-of-use we recommend moving this file to a directory in your shell’s PATH, renaming it, and making it executable. For example, in Linux:

cd /usr/local/bin
cp -p /home/<username>/Download/trino-cli-*-executable.jar .
mv trino-cli-*-executable.jar trino
chmod +x trino

You can run the same commands in macOS by replacing the directory in line two with /Users/<username>/Downloads/trino-cli-*-executable.jar.

Next, to verify that the installation works, run the following command:

trino --version

This command outputs a string with the CLI version you downloaded:

$ trino --version
Trino CLI 360

Connection #

Use the following steps to access your cluster with the Trino CLI client:

Get the necessary connection information for your cluster.
Launch the CLI with the --server option, specifying the host for your cluster. You can specify a custom port by appending :<port number> to the host.
```
trino --server=https://cluster.example.com
```

On a successful connection, a trino> prompt is displayed indicating that you are currently in a Trino CLI shell.

Authentication #

The Trino CLI and SEP support multiple authentication types to ensure all users are authenticated. Starburst Galaxy uses a username and password authentication system that works with your email address as username.

If the cluster requires password authentication, the client prompts you for your password. By default, the CLI client uses your operating system username to authenticate. You can override this default and specify a custom username with the --user option.

Run the command that matches your operating system:

For Linux and macOS

./trino --server <your-user-role-based-routing-URL or your-cluster-URL> --user <your-login-account>

For Windows

java -jar trino --server <your-user-role-based-routing-URL or your-cluster-URL> --user <your-login-account>

To connect to a cluster using external authentication, run the command that matches your operating system with --external-authentication appended.

For more advanced authentication options and additional information, see the following pages:

Authorization #

The Trino CLI and SEP support several authorization systems, including built-in access control. Note the specific behavior of the built in access control with the Trino CLI.

Starburst Galaxy supports role-based access control with numerous clients, including the Trino CLI.

Querying #

In the CLI command prompt, you can issue SQL queries against the cluster. You can review all available commands in the CLI shell with the HELP; command.

Note: All commands in the CLI shell must end with a semicolon.

The following example commands demonstrate some common operations you can do in the client:

To see the list of catalogs configured in the cluster, run a SHOW CATALOGS statement:
```
SHOW CATALOGS;
```
See the following example output:
```
trino> SHOW CATALOGS;
 Catalog
-----------
 jmx
 memory
 system
 tpcds
 tpch
(5 rows)
```

To see the available schemas in a catalog, run a SHOW SCHEMAS statement:

SHOW SCHEMAS FROM tpch;

See the following example output:

trino> SHOW SCHEMAS FROM tpch;
       Schema
--------------------
 information_schema
 sf1
 sf100
 sf1000
 sf10000
 sf100000
 sf300
 sf3000
 sf30000
 tiny
(10 rows)

To specify a catalog and schema for following queries, run a USE statement:
```
USE tpch.sf100;
```
See the following example output:
```
trino> USE tpch.sf100;
trino:sf100>
```

To see the available tables in a schema, run a SHOW TABLES statement:

SHOW TABLES FROM tpch.sf100;

See the following example output:

trino:sf100> SHOW TABLES;
  Table
----------
 customer
 lineitem
 nation
 orders
 part
 partsupp
 region
 supplier
(8 rows)

To see the structure of a table, run a SHOW COLUMNS statement:

SHOW COLUMNS FROM tpch.sf100.customer;

See the following example output:

trino:sf100> SHOW COLUMNS FROM customer;
   Column   |     Type     | Extra | Comment
------------+--------------+-------+---------
 custkey    | bigint       |       |
 name       | varchar(25)  |       |
 address    | varchar(40)  |       |
 nationkey  | bigint       |       |
 phone      | varchar(15)  |       |
 acctbal    | double       |       |
 mktsegment | varchar(10)  |       |
 comment    | varchar(117) |       |
(8 rows)

To run a query, enter it as a complete SQL statement:

SELECT custkey, name, phone, acctbal FROM tpch.sf100.customer LIMIT 7;

See the following example output:

trino:sf100> SELECT custkey, name, phone, acctbal FROM customer LIMIT 7;
"937501","Customer#000937501","21-593-223-9096","-543.06"
"937502","Customer#000937502","15-558-441-5619","764.44"
"937503","Customer#000937503","22-672-434-9488","8855.01"
"937504","Customer#000937504","12-286-528-4612","5136.01"
"937505","Customer#000937505","21-520-144-4196","1892.29"
"937506","Customer#000937506","31-167-767-9014","679.91"
"937507","Customer#000937507","27-398-220-4780","7159.44"

As demonstrated in these example commands, the Trino CLI uses supported SQL statements to review and query data sources connected to Starburst Galaxy or SEP.

To exit the CLI shell, run EXIT;:

trino:sf100> EXIT;

Querying outside of the CLI shell #

In addition to launching the Trino CLI and running queries from its shell, you can execute queries directly from your terminal with the --execute option and a query string:

trino --server cluster.example.com:8080 --execute 'SELECT custkey, name, phone, acctbal FROM tpch.sf100.customer LIMIT 7'
"937501","Customer#000937501","21-593-223-9096","-543.06"
"937502","Customer#000937502","15-558-441-5619","764.44"
"937503","Customer#000937503","22-672-434-9488","8855.01"
"937504","Customer#000937504","12-286-528-4612","5136.01"
"937505","Customer#000937505","21-520-144-4196","1892.29"
"937506","Customer#000937506","31-167-767-9014","679.91"
"937507","Customer#000937507","27-398-220-4780","7159.44"

You can also execute SQL script files with the --file option:

trino --server cluster.example.com:8080 --file 'nations.sql'
USE
"ALGERIA"
"ARGENTINA"
...
"UNITED KINGDOM"
"UNITED STATES"

This example uses a script, nations.sql, downloaded from the Trino: The Definitive Guide GitHub repository.

Next steps #

This guide explained basic connection instructions and example queries for the Trino CLI client. To learn more about what you can do with the CLI client, see the following resources:

Learn more about SQL statements that you can use with Starburst in the SQL guide.
Learn more about the CLI client in the SEP documentation.

Is the information on this page helpful?

Yes

Cancel

Clients

CLI #

Requirements #

Download and install #

Connection #

Authentication #

Authorization #

Querying #

Querying outside of the CLI shell #

Next steps #