使用命令行客户端连接 Lakehouse
本文介绍如何安装、配置和使用基于 sqlline 的 Lakehouse 命令行客户端。
💡 推荐使用 cz-cli：cz-cli 是本工具（sqlline）的升级替代方案，提供更现代的终端体验——Profile 管理（一次配置、全局复用）、结构化 JSON 输出、任务运维命令、AI Agent 集成等能力。sqlline 客户端已不再迭代更新，新用户建议直接使用 cz-cli。
→ 使用 cz-cli 命令行工具连接
前提条件
在开始使用客户端之前，请确保满足以下条件：
- 你的设备已安装 Java 8 或更高版本
- 你已在云器平台注册账户，并创建了 Lakehouse 服务实例
- 你已创建用于连接访问的工作空间
- 使用客户端的用户身份已被添加至工作空间，并被授权访问
安装客户端
Lakehouse 命令行客户端基于开源 SQL Line 项目进行二次开发。请按照以下步骤安装并配置客户端：
- 从公网下载或通过云器工作人员获取客户端安装包 sqlline_cz.tar.gz
- 解压安装包文件，你将获得客户端工具的可执行文件和配置文件：
tar -zxvf sqlline_cz.tar.gz
解压产物：
sqlline_cz/
├── example.properties
├── log4j.properties
├── setup.sh
├── sqlline
└── sqlline-2.13.0-SNAPSHOT-jar-with-dependencies.jar
初始化连接环境
- 进入工作目录：
cd sqlline_cz
- 初始化连接环境，下载最新的 JDBC 驱动包：
sh setup.sh
如 setup 脚本下载失败，可手动下载 JDBC 驱动并放到
sqlline_cz
sqlline_cz
目录下：
配置客户端连接
方式一：命令行指定连接参数
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 格式：
jdbc:clickzetta://<instance_name>.<region_id>.api.clickzetta.com/<workspace_name>?schema=<schema_name>&vcluster=<vcluster_name>
参数说明：
| 参数 | 说明 |
|---|
-d
-d | JDBC 驱动类名，固定为 com.clickzetta.client.jdbc.ClickZettaDriver
com.clickzetta.client.jdbc.ClickZettaDriver |
-u
-u | JDBC 连接 URL，详细格式见 JDBC 驱动 |
-n
-n | 工作空间成员用户名 |
-p
-p | 工作空间成员密码 |
schema
schema | 指定要连接的 Schema，必须填写 |
vcluster
vcluster | 使用的计算集群，必须填写 |
示例：
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
方式二：命令行指定配置文件
- 修改配置文件模板
example.properties
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>
- 通过配置文件连接：
sh sqlline properties test.properties
连接成功后，可在会话中用
!properties
!properties
命令快速切换到其他配置文件：
0: jdbc:clickzetta://xxxx.api.clickzetta.com> !properties test.properties.1
1: jdbc:clickzetta://yyyy.api.clickzetta.com>
运行 SQL 命令
连接成功后，你可以在命令行客户端执行 Lakehouse SQL 命令：
-- 切换 VCluster 和 Schema
use vcluster DEFAULT;
use schema nyc_taxi_data;
-- 查看当前 Schema 中有哪些表
show tables;
-- 查询数据
select * from fhv_trips_staging limit 10;
退出客户端
!quit
开启 Debug 日志
通过设置环境变量启用 Debug 模式，输出日志文件方便问题排查：
export SQLLINE_DEBUG_ENABLE=TRUE
相关文档
