命令行工具

IoTDB 为用户提供 CLI 工具用于和服务端程序进行交互操作。在使用 CLI 工具连接 IoTDB 前，请保证 IoTDB 服务已经正常启动。下面介绍 CLI 工具的运行方式和相关参数。

本文中 $IoTDB_HOME 表示 IoTDB 的安装目录所在路径。

1. CLI 启动

CLI 客户端脚本是 $IoTDB_HOME/sbin 文件夹下的start-cli脚本。启动命令为：

  • Linux/MacOS 系统常用启动命令为：
Shell> bash sbin/start-cli.sh -sql_dialect table
或
# V2.0.6.x 版本之前
Shell> bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -sql_dialect table
# V2.0.6.x 版本及之后
Shell> bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021 -sql_dialect table
  • Windows 系统常用启动命令为：
# V2.0.4.x 版本之前
Shell> sbin\start-cli.bat -sql_dialect table
或
Shell> sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -sql_dialect table

# V2.0.4.x 版本及之后
Shell> sbin\windows\start-cli.bat -sql_dialect table
或
# V2.0.4.x 版本及之后,  V2.0.6.x 版本之前
Shell> sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -sql_dialect table
# V2.0.6.x 版本及之后
Shell> sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021 -sql_dialect table

其中：

  • -h 和-p 项是 IoTDB 所在的 IP 和 RPC 端口号（本机未修改 IP 和 RPC 端口号默认为 127.0.0.1、6667）
  • -u 和-pw 是 IoTDB 登录的用户名密码（安装后IoTDB有一个默认用户，用户名为root,密码为TimechoDB@2021,V2.0.6版本之前密码为root）
  • -sql_dialect 是登录的数据模型（表模型或树模型），此处指定为 table 代表进入表模型模式

更多参数见：

参数名参数类型是否为必需参数说明示例
-h <host>string 类型否IoTDB 客户端连接 IoTDB 服务器的 IP 地址， 默认使用：127.0.0.1。-h 127.0.0.1
-p <rpcPort>int 类型否IoTDB 客户端连接服务器的端口号，IoTDB 默认使用 6667。-p 6667
-u <username>string 类型否IoTDB 客户端连接服务器所使用的用户名，默认使用 root。-u root
-pw <password>string 类型否IoTDB 客户端连接服务器所使用的密码，默认使用 TimechoDB@2021（V2.0.6版本之前为root）。-pw root
-sql_dialect <sql_dialect>string 类型否目前可选 tree（树模型） 、table（表模型），默认 tree-sql_dialect table
-e <execute>string 类型否在不进入客户端输入模式的情况下，批量操作 IoTDB。-e “show databases”
-c空否如果服务器设置了 rpc_thrift_compression_enable=true， 则 CLI 必须使用 -c-c
-disableISO8601空否如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 （timestamp）。-disableISO8601
-usessl <use_ssl>Boolean 类型否否开启 ssl 连接-usessl true
-ts <trust_store>string 类型否ssl 证书存储路径-ts /path/to/truststore
-tpw <trust_store_pwd>string 类型否ssl 证书存储密码-tpw myTrustPassword
-timeout <queryTimeout>int 类型否查询超时时间（秒）。如果未设置，则使用服务器的配置。-timeout 30
-help空否打印 IoTDB 的帮助信息。-help

启动后出现如图提示即为启动成功。

2. CLI 使用

2.1 执行语句

进入 CLI 后，用户可以直接在对话中输入 SQL 语句进行交互。如：

  • 创建数据库
create database test

  • 查看数据库
show databases

2.2 命令技巧

CLI中使用命令小技巧：

（1）快速切换历史命令: 上下箭头

（2）历史命令自动补全：右箭头

（3）中断执行命令: CTRL+C

3. CLI 退出

在 CLI 中输入quit或exit可退出 CLI 结束本次会话。

4. 访问历史功能

IoTDB V2.0.9.1 起支持开启访问历史功能，即客户端登录成功后展示关键的历史访问信息，支持分布式场景。管理员与普通用户仅可查看自身访问历史，核心展示内容包括：

  • 上一次成功会话：显示日期、时间、访问应用、IP地址及访问方法（首次登录或无历史记录时不显示）。
  • 最近一次失败尝试：显示距离本次成功登录时间最近的一次失败记录的日期、时间、访问应用、IP地址及访问方法。
  • 累计失败次数：统计自上一次成功会话建立以来，所有未成功建立的会话尝试总次数。

4.1 开启访问历史

支持通过修改 iotdb-system.properties 文件中的相关参数来控制是否开启访问历史功能，修改参数后需重启生效，例如：

# 用于控制是否启用审计日志功能
enable_audit_log=false
  • 开启时，记录登录信息并定期清理过期数据；
  • 关闭时，不记录、不展示、不清理；
  • 开关关闭后重开，展示的历史为关闭前最后一条记录，不一定代表真实最近登录记录。

使用示例：

---------------------
Starting IoTDB Cli
---------------------
 _____       _________  ______   ______    
|_   _|     |  _   _  ||_   _ `.|_   _ \   
  | |   .--.|_/ | | \_|  | | `. \ | |_) |  
  | | / .'`\ \  | |      | |  | | |  __'.  
 _| |_| \__. | _| |_    _| |_.' /_| |__) | 
|_____|'.__.' |_____|  |______.'|_______/  Enterprise version 2.0.9.1 (Build: xxxxxxx)
                                           

---Last Successful Session------------------
Time: 2026-03-24T10:25:47.759+08:00
IP Address: 127.0.0.1
---Last Failed Session----------------------
Time: 2026-03-24T10:27:26.314+08:00
IP Address: 127.0.0.1
Cumulative Failed Attempts: 1
Successfully login at 127.0.0.1:6667
IoTDB>

4.2 查看访问历史

root 用户及具有 AUDIT 权限的用户可以通过 SQL 语句查看访问历史记录。

语法定义：

select * from __audit.login_history;

示例：

IoTDB> select * from __audit.login_history
+-----------------------------+-------+-------+--------+---------+------+
|                         time|user_id|node_id|username|       ip|result|
+-----------------------------+-------+-------+--------+---------+------+
|2026-03-25T10:55:58.240+08:00|    u_0| node_1|    root|127.0.0.1|  true|
+-----------------------------+-------+-------+--------+---------+------+
Total line number = 1
It costs 0.213s