Upsolver SQLake
Search…
⌃K

CLI

Upsolver CLI is the next-generation command line client that provides a terminal-based interactive shell for running queries. It connects to Upsolver to execute SQL statements and perform all DDL and DML operations, including loading data as a continuous stream to various data destinations.
Upsolver CLI provides a command line interface to interact with the Upsolver API endpoint. The CLI connects to a Upsolver service and interacts with it through the service's endpoint.

CLI supports two types of requests:

  1. 1.
    Ordinary API requests where a request is submitted and the response is received completely. In this case, the Upsolver prompt in the CLI shows the response as well as the prompt to receive the next request/command from the user.
  2. 2.
    Streaming requests where the response is an unbounded stream of data that is sent by the Upsolver service. This type of response is generated for COPY or INSERT statements. They can be terminated by dropping the job.

Install Upsolver CLI

python 3.10+ is required for installing Upsolver CLI.
A connection is not a prerequisite for installing Upsolver CLI. All required software for installing Upsolver CLI is bundled in the installers.
Upsolver provides platform-specific versions of Upsolver CLI for download for the following platforms:
Operating system
Supported versions
macOS
10.14, 10.15
Windows
Microsoft Windows 8, 8.1, 10 Microsoft Windows Server 2012, 2016, 2019

Install on MacOS using Homebrew Cask

You can install the CLI tool using Homebrew:
$ brew tap upsolver/cli https://github.com/Upsolver/cli
$ brew install upsolver-cli

Install on Linux / Windows using PIP

Make sure you have Python 3.10+ installed, and then use pip to install the CLI tool:

Use Upsolver CLI

Lines are read one at a time and are sent as Upsolver CLI unless one of the following is true:
  1. 1.
    The line is empty or entirely whitespace. In this case, no request is made.
  2. 2.
    The line is not a built-in CLI command and does not end with a semicolon. In this case, the CLI enters multi-line mode where lines are continuously read until a line is encountered that is terminated with a semicolon. The concatenation of all lines read during this time is sent as Upsolver CLI.

Options

Option
Description
--version
Shows the version and exits
-p, --profile TEXT
Commands are executed using the provided profile's authorization token
-c, --config TEXT
Path and name of the UpSQL configuration file
-o, --option TEXT
Sets UpSQL option(s)
--debug
Sets logging level to DEBUG and log to stdout
-h, --help
Displays the help message with the list of available options and commands and exits.

Commands

Command
Description
authenticate
Retrieves the API token to perform further actions
catalogs
View & manage catalogs (connections)
clusters
View & manage compute clustersA
execute
Executes a single SQL query
jobs
View & manage jobs
tables
View & manage tables

Authentication

Authenticating using the CLI requires API token and API endpoint.
Using upsolver configure to authenticate.

Example

% upsolver configure
API Access Token [5fcf1025c6e2413db4fa32dc23227d5b]: 5fcf1025c6e2413db4fa32dc23227d5b
API Endpoint [https://api-d1231eb0-456d-4708-a393-6be41a770722.upsolver.com]: https://api-d1231eb0-456d-4708-a393-6be41a770722.upsolver.com
Default Output Format [json]: json
The configuration profile will be located under ~/.upsolver/config You may have multiple profiles defined if multiple accounts are needed.

Example

[profile]
token = 5fcf1025c6e2413db4fa32dc23227d5b
base_url = https://api-d1231eb0-456d-4708-a393-6be41a770722.upsolver.com
output = JSON
[susie]
token = 3fcf1025c6e1234db4fa32dc5678d5b
base_url = https://api-d4321eb0-456d-4708-a393-6be41a123455.upsolver.com
output = JSON
In the example above, you may use upsolver -p susie catalogs ls to run statements using a specific profile.
$ upsolver clusters ls
{
"name": "Private API",
"id": "d1231eb0-371d-4708-a393-6be41a770722"
}
{
"name": "Default Compute",
"id": "1dawer980d-c4d2-4db8-af9b-911bef9cb4ad"
}
{
"name": "Default Query",
"id": "bf684321-941a-23d3-a00a-50d281ba2edd"
}