Apache Phoenix 5.2 常用 CLI 命令与工具详解

Apache Phoenix 5.2.1（配 HBase 2.4.18）常用 CLI 命令与工具详解，涵盖 sqlline 连接与 SQL 命令、! 元命令、以及 psql 批量加载工具，附真实回显与速查表。

Apache PhoenixApache Phoenix2026/10/11

Apache Phoenix 5.2 常用 CLI 命令与工具详解

目标：本文详解 Apache Phoenix 5.2.1（配 HBase 2.4.18）的常用 CLI 与工具——sqlline.py（交互式 SQL 客户端）与 psql.py（批量加载/执行工具），覆盖连接方式、SQL 与 ! 元命令、真实回显及速查表；所有命令与输出已在 Ubuntu 22.04.5 环境实测。

一、环境信息

项值
操作系统Ubuntu 22.04.5 LTS（x86_64）
账号root
JDKOpenJDK 11.0.32.1（JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64）
Phoenix5.2.1（/opt/phoenix，单元 sqlline.py、psql.py、schemavars.txt 等在 /opt/phoenix/bin）
sqllineversion 1.9.0（JDBC URL jdbc:phoenix:localhost:2181）
连接地址单机内嵌 ZooKeeper：localhost:2181

二、工具概览

工具脚本用途依赖
sqlline/opt/phoenix/bin/sqlline.py交互式/批处理 SQL 客户端，执行 DDL/DML/查询与元命令Python 3 + JDK 11
psql/opt/phoenix/bin/psql.py执行 SQL 脚本、加载 CSV TXT 数据、批量 DDLPython 3 + JDK 11
（数据校验回显）无CREATE/UPSERT/SELECT/ALTER/psql 的真实输出见下文—

💡 说明：两者均为 Python 包装脚本，内部拼 Java 命令；JVM 堆通过环境变量 PHOENIX_OPTS 传入（详见 §三）。

三、前置条件

  1. 已启动 HBase + Phoenix（jps 可见 HMaster，端口 2181/16000/16010/16020/16030 在监听），详见同专栏《Ubuntu 22.04 安装 Apache Phoenix 5.2 指南》。
  2. 具备 Python 3 与 JDK 11；客户端 JVM 堆限制在 256MB（后续命令用 PHOENIX_OPTS 注入）。

四、sqlline.py 交互式 SQL 客户端详解

4.1 连接

启动 sqlline 连接单机内嵌 ZooKeeper，并限制客户端堆：

PHOENIX_OPTS="-Xms256m -Xmx256m" /opt/phoenix/bin/sqlline.py localhost:2181

sqlline version 1.9.0
0: jdbc:phoenix:localhost:2181>

集群环境连接串写多个 ZK 节点：/opt/phoenix/bin/sqlline.py zk1:2181,zk2:2181,zk3:2181。

⚠️ 注意：非 TTY（脚本/管道）下列宽会被压缩为空，先执行 !set maxwidth 200; 与 !set maxcolumnwidth 30; 再查询。

4.2 建表（CREATE TABLE）

0: jdbc:phoenix:localhost:2181> CREATE TABLE IF NOT EXISTS user (id INTEGER PRIMARY KEY, name VARCHAR);
No rows affected (0.787 seconds)

说明：主键 id INTEGER PRIMARY KEY 即 HBase 行键；VARCHAR 为列类型。

4.3 写入（UPSERT）

Phoenix 用 UPSERT（存在则更新、不存在则插入）代替标准 INSERT：

0: jdbc:phoenix:localhost:2181> UPSERT INTO user VALUES (1, 'Alice');
1 row affected (0.069 seconds)

4.4 查询（SELECT）

0: jdbc:phoenix:localhost:2181> SELECT id, name FROM user;
+----+-------+
| ID | NAME  |
+----+-------+
| 1  | Alice |
+----+-------+
1 row selected (0.065 seconds)

4.5 修改表结构（ALTER）

0: jdbc:phoenix:localhost:2181> ALTER TABLE user ADD age INTEGER;
No rows affected (6.04 seconds)

添加列后 UPSERT 新行并查询（体现多列）：

0: jdbc:phoenix:localhost:2181> UPSERT INTO user VALUES (2, 'Bob', 30);
1 row affected (0.118 seconds)
0: jdbc:phoenix:localhost:2181> SELECT id, name, age FROM user;
+----+-------+------+
| ID | NAME  | AGE  |
+----+-------+------+
| 1  | Alice | null |
| 2  | Bob   | 30   |
+----+-------+------+
2 rows selected (0.082 seconds)

说明：ALTER TABLE <表名> ADD <列名> <列类型> 动态加列（本例为 ALTER TABLE user ADD age INTEGER）；已有行 age 为 NULL，新写入的行存 30。

4.6 删除与回收

0: jdbc:phoenix:localhost:2181> DELETE FROM user WHERE id=2;
1 row affected (0.112 seconds)
0: jdbc:phoenix:localhost:2181> SELECT id, name FROM user;
+----+-------+
| ID | NAME  |
+----+-------+
| 1  | Alice |
+----+-------+
1 row selected (0.084 seconds)

删除测试表：

0: jdbc:phoenix:localhost:2181> CREATE TABLE IF NOT EXISTS test_drop (id INTEGER PRIMARY KEY, v VARCHAR);
No rows affected (0.884 seconds)
0: jdbc:phoenix:localhost:2181> DROP TABLE test_drop;
No rows affected (0.594 seconds)

4.7 查看表清单（!tables）

列出 SYSTEM 系统表与用户表：

0: jdbc:phoenix:localhost:2181> !tables
+-----------+-------------+------------+--------------+---------+-----------+---------------------------+----------------+-------------+----------------+--------------+--------------+----------------+
| TABLE_CAT | TABLE_SCHEM | TABLE_NAME |  TABLE_TYPE  | REMARKS | TYPE_NAME | SELF_REFERENCING_COL_NAME | REF_GENERATION | INDEX_STATE | IMMUTABLE_ROWS | SALT_BUCKETS | MULTI_TENANT | VIEW_STATEMENT |
+-----------+-------------+------------+--------------+---------+-----------+---------------------------+----------------+-------------+----------------+--------------+--------------+----------------+
|           | SYSTEM      | CATALOG    | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | CHILD_LINK | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | FUNCTION   | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | LOG        | SYSTEM TABLE |         |           |                           |                |             | true           | 32           | false        |                |
|           | SYSTEM      | MUTEX      | SYSTEM TABLE |         |           |                           |                |             | true           | null         | false        |                |
|           | SYSTEM      | SEQUENCE   | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | STATS      | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | TASK       | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           | SYSTEM      | TRANSFORM  | SYSTEM TABLE |         |           |                           |                |             | false          | null         | false        |                |
|           |             | USER       | TABLE        |         |           |                           |                |             | false          | null         | false        |                |
+-----------+-------------+------------+--------------+---------+-----------+---------------------------+----------------+-------------+----------------+--------------+--------------+----------------+

4.8 sqlline 元命令速查（! 开头）

命令作用实测示例
!set maxwidth <n>设置列最大宽度（非 TTY 必需）!set maxwidth 200;
!set maxcolumnwidth <n>设置单列最大宽度!set maxcolumnwidth 30;
!tables列出全部表（含 SYSTEM 表）见 4.7
!quit / !exit退出 sqlline!quit
!help查看全部 ! 元命令帮助!help
!describe <表> / !dbinfo查看表结构 / 数据库信息!describe user

五、psql.py 批量执行与数据加载详解

5.1 用法

psql 可执行 SQL 脚本并把表数据落表，同时支持 CSV 批量加载。用法：

usage: psql [-t table-name] [-h comma-separated-column-names | in-line]
            [-d field-delimiter-char quote-char escape-char]<zookeeper>
            <path-to-sql-or-csv-file>...

常用示例：

/opt/phoenix/bin/psql.py localhost:2181 my_ddl.sql
/opt/phoenix/bin/psql.py localhost:2181 my_ddl.sql my_table.csv
/opt/phoenix/bin/psql.py -t MY_TABLE my_cluster:2181 my_table2012.csv

5.2 主要参数

参数说明
-t,--table <arg>指定 CSV 数据要加载进的目标表（区分大小写）
-h,--header <arg>指定 CSV 列名映射（区分大小写）；in-line 表示首行即列名
-d,--delimiter <arg>字段分隔符（1–9 对应 Ctrl-A 到 Ctrl-I）
-s,--strict严格模式：列名不匹配即抛异常
-l,--local-index-upgrade升级本地索引（索引数据从独立表移入同表列族）
-m,--map-namespace <arg>将表映射到与 schema 同名 namespace（需开启 phoenix.schema.isNamespaceMappingEnabled）
-u,--upgrade按正确行键重写降序列以升级表
-b,--binaryEncoding <arg>指定二进制编码
-a,--array-separator <arg>数组元素分隔符，默认 :
-q,--quote-character <arg>CSV 引号字符
-e,--escape-character <arg>CSV 转义字符

⚠️ 注意：-t/-h 表名与列名均区分大小写；无输入文件时 psql 报 At least one input file must be supplied。

5.3 实践：CSV 批量加载

准备 CSV 与建表脚本：

printf "id,name\n1,Alice\n2,Bob\n" > /tmp/user.csv
printf "CREATE TABLE IF NOT EXISTS user_csv (id INTEGER PRIMARY KEY, name VARCHAR);\n" > /tmp/create.sql

执行 psql 建表并加载（-t user_csv 指定目标表，-h in-line 用首行作列名）：

PHOENIX_OPTS="-Xms256m -Xmx256m" /opt/phoenix/bin/psql.py localhost:2181 /tmp/create.sql
PHOENIX_OPTS="-Xms256m -Xmx256m" /opt/phoenix/bin/psql.py -t user_csv -h in-line localhost:2181 /tmp/user.csv

💡 说明：-h in-line 要求 CSV 首行是列名（id,name），行内容按列映射写入；批量加载内置批次提交，适合大批数据导入。

六、注意事项

  1. 客户端堆：sqlline.py/psql.py 均通过 PHOENIX_OPTS 传 JVM 参数，统一限 -Xms256m -Xmx256m；服务端堆由 hbase-env.sh 的 HBASE_HEAPSIZE 控制（512m），改后以 jps -v 复核。
  2. 非 TTY 列宽：脚本/管道执行 sqlline 记得先 !set maxwidth，否则结果列被压缩为空。
  3. 首连重连：首次连接偶现对 IPv6 地址的瞬时 Connection refused，客户端自动重连后恢复（WARN 可忽略）。
  4. 连接串：localhost:2181 为单机内嵌 ZooKeeper；集群写多 ZK 节点，psql 同格式。
  5. 命令真实性：上表命令均为实测回显，sqlline 1.9.0、Phoenix 5.2.1。

七、常见问题（FAQ）

Q1：sqlline 查询结果列全部空白。 非交互终端下列宽被压缩，先执行 !set maxwidth 200; 与 !set maxcolumnwidth 30; 再查询。

Q2：首次连接报 Connection refused。 瞬时 IPv6 连接失败，客户端自动重连恢复，不影响建表/写入/查询，可忽略。

Q3：ALTER TABLE 加列提示超时或较慢。 加列会触发元数据更新（少量数据规模下实测约数秒），大表加列需在低峰期操作并可放宽 phoenix.query.timeoutMs。

Q4：psql 报 At least one input file must be supplied。 psql 必须给 -t/-h 配置时同时提供 SQL 或 CSV 文件路径；仅运行空参数无法进入交互，与 sqlline 不同。

Q5：psql 加载时列名对不上。 确认 -h 指定的列名与你表定义一致且区分大小写；或用 -h in-line 让首行文件头定义列名。严格校验可加 -s。

Q6：CSV 含特殊分隔符。 指定 -d 自定义分隔符（数字 1–9 对应 Ctrl-A 到 Ctrl-I），加 -q 引号字符与 -e 转义字符处理含分隔符的字段。

八、参考链接