| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| |
| # 命令行工具 |
| |
| IoTDB 为用户提供 CLI 工具用于和服务端程序进行交互操作。在使用 CLI 工具连接 IoTDB 前，请保证 IoTDB 服务已经正常启动。下面介绍 CLI 工具的运行方式和相关参数。 |
| |
| > 本文中 $IoTDB_HOME 表示 IoTDB 的安装目录所在路径。 |
| |
| ## 1. CLI 启动 |
| |
| CLI 客户端脚本是 $IoTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动命令为： |
| |
| - Linux/MacOS 系统常用启动命令为： |
| |
| ```Shell |
| 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 系统常用启动命令为： |
| |
| ```Shell |
| # 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 语句进行交互。如： |
| |
| - 创建数据库 |
| |
| ```Java |
| create database test |
| ``` |
| |
|  |
| |
| |
| - 查看数据库 |
| |
| ```Java |
| 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` 文件中的相关参数来控制是否开启访问历史功能，修改参数后需重启生效，例如： |
| |
| ```Plain |
| # 用于控制是否启用审计日志功能 |
| enable_audit_log=false |
| ``` |
| |
| * 开启时，记录登录信息并定期清理过期数据； |
| * 关闭时，不记录、不展示、不清理； |
| * 开关关闭后重开，展示的历史为关闭前最后一条记录，不一定代表真实最近登录记录。 |
| |
| 使用示例： |
| |
| ```Bash |
| --------------------- |
| 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 语句查看访问历史记录。 |
| |
| 语法定义： |
| |
| ```SQL |
| select * from __audit.login_history; |
| ``` |
| |
| 示例： |
| |
| ```SQL |
| 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 |
| ``` |
