ByteHouse CLI 是一个命令行应用程序，用于以最直接的方式与 ByteHouse 服务交互，您可以直接使用秘钥对连接 ByteHouse CLI 并执行资源创建管理、SQL 查询等操作。本文将介绍如何安装和使用 ByteHouse CLI。

准备工作

如果您的系统是 macOS，请先安装 Homebrew，本文将使用 Homebrew 安装 ByteHouse CLI。Homebrew 安装操作请参见官方网站。

安装

您可以从官方仓库获取最新的 ByteHouse CLI 发布版本。

macOS Homebrew 安装

安装

打开您的终端，运行如下 Homebrew 命令安装 ByteHouse CLI。

brew tap bytehouse-cloud/homebrew-core
brew install bytehouse-cli

安装完成后，可以通过下面的命令查询当前安装的版本，确保安装已经完成。

bytehouse-cli -v

查询结果示例：

升级

如果要升级您的 ByteHouse CLI 版本，可以运行下列命令。

brew upgrade bytehouse-cli

故障处理

如果您已经安装了 ByteHouse CLI，但在重新安装或升级时遇到一些错误，请尝试使用以下步骤处理故障。

1. 卸载 ByteHouse CLI。

   brew uninstall bytehouse-cli
   brew untap bytehouse-cloud/homebrew-core
   

2. 执行下面的命令重新安装。

   brew tap bytehouse-cloud/homebrew-core
   brew install bytehouse-cli
   

Linux 系统

对于 Linux 系统，请从 GitHub 发布地址中获取最新发布版本的链接，替换以下命令中的链接，并参考下面的代码操作。

# 请从上面的发布地址中获取最新链接，或替换下面代码中的版本号
# 使用最新发布版本替换下面的第一行内容
curl -o bytehouse-cli.tar.gz -L https://github.com/bytehouse-cloud/cli/releases/download/v<版本号>/bytehouse-cli_<版本号>_Linux_x86_64.tar.gz     # 替换该链接地址或版本号
mkdir -p ./bytehouse-cli/
tar -zxvf bytehouse-cli.tar.gz -C ./bytehouse-cli
chmod +x bytehouse-cli 

# 将这个二进制可执行文件作为别名添加到 ~/.bashrc 文件中，或者添加到 ~/.zshrc 文件中
echo "alias bytehouse-cli=\"$(pwd)/bytehouse-cli\"" >> ~/.bashrc

Windows 系统

对于 Windows 系统，请选择 GitHub 地址中的最新版本，下载安装包并进行解压及安装。
下载的压缩包示例格式如下：bytehouse-cli_1.26.8_Windows_x86_64.zip

连接到 ByteHouse

ByteHouse 支持通过 IAM 用户或数据库用户连接。IAM 用户与数据库用户二者差异说明如下，您可按需选择。

• IAM 用户为火山引擎访问控制（IAM）中创建的用户，其权限由 IAM 权限策略及您授予的 ByteHouse 资源和数据权限决定。IAM 用户可访问 ByteHouse 控制台，也支持通过 CLI、连接驱动、生态工具、API 等方式访问 ByteHouse。
• 数据库用户为 ByteHouse 中创建的数据库级别用户，可为其授予环境、资源和数据权限。数据库用户不可访问 ByteHouse 控制台，但支持通过 CLI、连接驱动、生态工具、API 等方式访问 ByteHouse。

更多 IAM 用户和数据库用户的介绍请参见以下文档：

• ByteHouse权限管控概述
• 管理 IAM 用户
• 管理数据库用户

使用 IAM 用户连接

可参考如下命令进行连接：

bytehouse-cli --host {HOST} --port 19000 --secure --token {API_KEY} 

示例如下：

bytehouse-cli --host tenant-{TENANT_ID}-{REGION}-{ENVIRONMENT}-public.bytehouse.volces.com --port 19000 --secure --token XXXXXXXXXXXXX

# 更多配置参数示例
bytehouse-cli --host tenant-{TENANT_ID}-{REGION}-{ENVIRONMENT}-public.bytehouse.volces.com --port 19000 --secure --token XXXXXXXXXXXXX --send_timeout=3600 --read_timeout=3600 --virtual_warehouse=warehouse1 --database=db1

参数说明如下，更多 flag 标志及缩写可以参考 CLI 配置参数文档。

使用数据库用户连接

可参考如下命令进行连接：

bytehouse-cli --user {accountID_or_accountName}::{username}[::{envID}] --password {password} --host {HOST} --port 19000 --secure

示例如下：

bytehouse-cli --user 21XXXXXXXX::demodb::testenv --password XXXXXXXX--host tenant-{TENANT_ID}-{REGION}-{ENVIRONMENT}-public.bytehouse.volces.com --port 19000 --secure

参数说明如下，更多 flag 标志及缩写可以参考 CLI 配置参数文档。

非交互模式

有时可能由于正在编写 shell 脚本而无法进入交互模式。ByteHouse CLI 允许用户执行 SQL 命令并自动退出。

使用查询标志

如果使用 -q 或 --query 标志启动 bytehouse-cli，将会执行 SQL 语句，并且 bytehouse-cli 会在执行后立即退出。

bytehouse-cli --host {HOST} --port 19000 --secure --token {API_KEY} -q "select 1" 

使用 stdin

您还可以在 bytehouse-cli 中使用 stdin 的输入。

echo "select 1" | bytehouse-cli

编写脚本

您也可以编写 SQL 脚本并将输入通过管道传输到 bytehouse-cli：

• 查询用 ; 分隔。
• 查询将按顺序运行。
• 如果第一次查询执行返回错误，请停止继续执行。

$ cat example.sql
CREATE DATABASE bob_db;
USE bob_db;
CREATE TABLE bob_number
(
   i Int32
)
ENGINE = CnchMergeTree
ORDER BY i;
SHOW CREATE TABLE bob_number;

$ bytehouse-cli < example.sql

# This is also accepted
$ cat example.sql | bytehouse-cli

数据插入

从文件中加载数据是一种常见的做法，下面是一些操作示例。

从查询中插入数据

交互模式

Bytehouse » INSERT INTO bob_db.bob_number VALUES (1), (2), (3) 

非交互模式

$ bytehouse-cli -q "INSERT INTO bob_db.bob_number VALUES (1), (2), (3)"

从本地文件中插入数据

交互模式

Bytehouse » INSERT INTO bob_db.bob_number FORMAT csv INFILE 'path/to/data.csv'

非交互模式

$ bytehouse-cli -q "INSERT INTO bob_db.bob_number FORMAT csv" < 'path/to/data.csv'

数据导出

查询后可通过 INTO OUTFILE 语法将结果保存到本地文件，导出文件的相对路径以启动 bytehouse-cli 时的当前工作目录为准。

Bytehouse » SELECT * FROM bob_db.bob_number INTO OUTFILE 'out.csv' format csv

如果需要保留查询结果的表头，则需要导出为 CSVWithNames 格式：

Bytehouse » SELECT * FROM bob_db.bob_number INTO OUTFILE 'out.csv' format CSVWithNames

版本检查

可以使用 -v 或 --version 标志检查 ByteHouse CLI 的版本。指定标志时，ByteHouse CLI 不启动。

$ bytehouse-cli -v
v1.5.2

帮助

使用 -h 标志或 --help 可以显示所有支持的标志。

#显示所有标志及其别名
bytehouse-cli -h