Connect to Lakehouse Using the Command Line Client

This article describes how to install, configure, and use the sqlline-based Lakehouse command line client.

💡 cz-cli is recommended: cz-cli is the upgraded replacement for this tool (sqlline), offering a more modern terminal experience—Profile management (configure once, reuse globally), structured JSON output, task operations commands, AI Agent integration, and more. The sqlline client is no longer actively updated; new users are advised to use cz-cli directly.

→ Connect using the cz-cli command line tool

Prerequisites

Before using the client, ensure the following conditions are met:

Your device has Java 8 or a higher version installed
You have registered an account on the Singdata platform and created a Lakehouse service instance
You have created a workspace for connection access
The user identity using the client has been added to the workspace and authorized for access

Installing the Client

The Lakehouse command line client is a secondary development of the open-source SQL Line project. Follow these steps to install and configure the client:

Download the client installation package sqlline_cz.tar.gz from the public network or obtain it from Singdata staff
Unzip the installation package file to get the client tool's executable and configuration files:

tar -zxvf sqlline_cz.tar.gz

Extracted contents:

sqlline_cz/ ├── example.properties ├── log4j.properties ├── setup.sh ├── sqlline └── sqlline-2.13.0-SNAPSHOT-jar-with-dependencies.jar

Initialize Connection Environment

Enter the working directory:

cd sqlline_cz

Initialize the connection environment, downloading the latest JDBC driver:

sh setup.sh

If the setup script fails to download, manually download the JDBC driver and place it in the sqlline_cz directory:

Configure Client Connection

Method 1: Specify Connection Parameters via Command Line

sh sqlline -d com.clickzetta.client.jdbc.ClickZettaDriver \ -u "jdbc:clickzetta://<instance>.<region>.api.clickzetta.com/<workspace>?schema=<schema>&vcluster=<vcluster>" \ -n <user_name> \ -p <password>

JDBC URL format:

jdbc:clickzetta://<instance_name>.<region_id>.api.clickzetta.com/<workspace_name>?schema=<schema_name>&vcluster=<vcluster_name>

Parameter descriptions:

Parameter	Description
`-d`	JDBC driver class name, fixed as `com.clickzetta.client.jdbc.ClickZettaDriver`
`-u`	JDBC connection URL, see JDBC Driver for full format
`-n`	Workspace member username
`-p`	Workspace member password
`schema`	Specifies the Schema to connect to, required
`vcluster`	Virtual Cluster to use, required

Example:

sh sqlline -d com.clickzetta.client.jdbc.ClickZettaDriver \ -u "jdbc:clickzetta://my_instance.cn-shanghai-alicloud.api.clickzetta.com/my_workspace?schema=public&vcluster=DEFAULT" \ -n data_user \ -p your_password

Method 2: Specify Configuration File via Command Line

Modify the configuration file template example.properties:

url=jdbc:clickzetta://<instance>.<region>.api.clickzetta.com/<workspace>?schema=<schema>&vcluster=<vcluster> driver=com.clickzetta.client.jdbc.ClickZettaDriver user=<your_user_name> password=<your_password>

Connect using the configuration file:

sh sqlline properties test.properties

After connecting, use the !properties command to quickly switch to another configuration file within the session:

0: jdbc:clickzetta://xxxx.api.clickzetta.com> !properties test.properties.1 1: jdbc:clickzetta://yyyy.api.clickzetta.com>

Running SQL Commands

After a successful connection, you can execute Lakehouse SQL commands in the command line client:

-- Switch Virtual Cluster and Schema use vcluster DEFAULT; use schema nyc_taxi_data; -- View tables in the current Schema show tables; -- Query data select * from fhv_trips_staging limit 10;

Exit Client

!quit

Enable Debug Logging

Enable debug mode by setting an environment variable to output log files for troubleshooting:

export SQLLINE_DEBUG_ENABLE=TRUE