全部产品
Search
文档中心

云原生多模数据库 Lindorm:通过Lindorm-cli连接并使用宽表引擎

更新时间:Jul 14, 2026

Lindorm-cli是Lindorm提供的简易命令行工具,用于连接和管理Lindorm数据库。您可以通过Lindorm-cli完成基本的SQL操作,例如建表、数据查询、数据写入和导出等。本文介绍通过Lindorm-cli连接并使用云原生多模数据库 Lindorm宽表引擎的方法。

前提条件

我们定义运行 lindorm-cli 的环境为客户端环境。在实际运行 lindorm-cli 访问 Lindorm 宽表引擎前,必须确认以下内容:

  • 已将客户端IP地址添加至Lindorm 的白名单,具体操作请参见设置白名单

  • 客户端环境与 Lindorm 之间的网络类型是哪种。

    lindorm-cli 连接宽表引擎可使用的网络类型如下:

    网络类型

    说明

    专有网络VPC(推荐)

    专有网络VPC(Virtual Private Cloud)是您自己的云上私有网络,不同的专有网络之间二层逻辑隔离,具有较高的安全性。Lindorm-cli部署在ECS实例上时,通过专有网络连接至Lindorm宽表,可获得更高的安全性和更低的网络延迟。

    公网

    公网即互联网,当本地设备需要测试或管理Lindorm宽表时,可在本地设备上部署Lindorm-cli,然后通过公网连接至Lindorm宽表。

    说明
    • 通过公网连接不会产生流量费用,但存在一定的安全风险,推荐通过专有网络连接以获取更高的安全性。

    • 公网地址需要在控制台开通。如何开通,请参见操作步骤

安装方法

  1. 根据您的操作系统,下载对应的Lindorm-cli安装包,下载链接如下表所示。

    说明

    下表中SHA256校验和可用于验证下载的Lindorm-cli安装包的完整性和真实性。

    操作系统

    下载链接

    SHA256校验码

    Linux

    lindorm-cli for linux

    命令直接下载:

    wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-latest.tar.gz

    3a9ee33e24769cf47b3a90c3a1bba29d26f8aede7a64dbc13ea1f4f5426f04e4

    Linux-arm64

    lindorm-cli for linux-arm64

    命令直接下载:

    wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-arm64-latest.tar.gz

    bc723d4a3a14a85c973c7082a56bb4934a40d2b9cccd72b5767352b8c334ce19

    Mac(Intel芯片)

    lindorm-cli for mac

    34efd3f43a700e1fea72ee5e5933b9df3cf624569bcf59a2f8a6752dc7faab6c

    Mac(Arm芯片)

    lindorm-cli for mac

    0be9b346404a37d953714377b59f06b6492ff9c4e46dba4d5bf07c390ee284ad

    Windows

    lindorm-cli for windows-x64

    54a447f263b93b158533f7ccd542cbf52e42fb66ce287d38065a798b7801fc48

  2. 解压Lindorm-cli压缩包。

    在不同的操作系统上,使用该操作系统解压缩包的常用方法解开先前所下载的压缩包。

    以Linux操作系统为例,执行以下命令解压。解压后可得到lindorm-cli文件。它是一个可执行文件,无需额外安装操作即可在 Shell 终端中直接执行。

    tar zxvf lindorm-cli-linux-latest.tar.gz

连接方法

lindorm-cli 同时支持以 MySQL 协议或者 Avatica 协议连接 Lindorm 宽表引擎,优先推荐使用 MySQL 协议来连接宽表引擎。

重要

2.0.0以上版本的lindorm-cli支持通过MySQL协议连接宽表引擎。

通过MySQL协议连接宽表引擎(推荐)

客户端部署在Linux或Mac系统

  1. 跳转至Lindorm-cli所在目录。

    cd <Lindorm-cli所在目录>
  2. 执行以下语句连接宽表引擎。

    ./lindorm-cli -url <mysql url> -username <用户名> -password <密码>

    参数说明

    参数

    说明

    mysql url

    Lindorm宽表引擎的MySQL兼容地址。更多连接配置请参见连接配置说明

    用户名

    连接Lindorm宽表引擎的用户名

    密码

    连接Lindorm宽表引擎的密码

    重要
    • 如果忘记密码,可以通过Lindorm宽表引擎的集群管理系统修改用户密码

    • 修改密码后,请通过控制台重启引擎。

    连接配置说明

    支持的连接配置

    说明

    mysql://协议头

    支持在mysql url前添加mysql://协议头。

    例如:mysql://ld-8vbn68478unu8****-proxy-sql-lindorm.lindorm.rds.aliyuncs.com:33060

    服务端自定义连接参数

    您可以在mysql url后设置服务端自定义连接参数,格式为key1=value1&key2=value2

    目前支持的参数如下:

    operationTimeout:表示查询超时时间。格式为<mysql url>?operationTimeout=<超时时间>,其中超时时间单位为毫秒(ms)。例如:ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000

    重要

    仅宽表引擎2.7.7及以上版本支持添加超时参数operationTimeout。如何查看或升级当前版本,请参见宽表引擎版本说明升级小版本

    连接示例

    ./lindorm-cli -url ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test
    
    --添加mysql://协议头连接
    ./lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test
    
    --指定查询超时时间
    ./lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000 -username user -password test

    连接成功将返回以下结果:

    lindorm-cli version: 2.0.x

    其中,2.0.x为Lindorm-cli的版本号。

客户端部署在Windows系统

方法一
  1. 打开命令提示符(CMD),跳转至lindorm-cli.exe的所在目录下。

    cd <lindorm-cli.exe所在目录>
  2. 在CMD上执行以下语句连接宽表引擎。

    lindorm-cli -url <mysql url> -username <用户名> -password <密码>

    参数说明

    参数

    示例值

    获取方法

    mysql url

    ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060

    Lindorm宽表引擎的MySQL兼容地址。更多连接配置请参见连接配置说明

    用户名

    user

    连接Lindorm宽表引擎的用户名

    密码

    test

    连接Lindorm宽表引擎的密码

    重要
    • 如果忘记密码,可以通过Lindorm宽表引擎的集群管理系统修改用户密码

    • 修改密码后,请通过控制台重启引擎。

    连接配置说明

    支持的连接配置

    说明

    mysql://协议头

    支持在mysql url前添加mysql://协议头。

    例如:mysql://ld-8vbn68478unu8****-proxy-sql-lindorm.lindorm.rds.aliyuncs.com:33060

    服务端自定义连接参数

    您可以在mysql url后设置服务端自定义连接参数,格式为key1=value1&key2=value2

    目前支持的参数如下:

    operationTimeout:表示查询超时时间。格式为<mysql url>?operationTimeout=<超时时间>,其中超时时间单位为毫秒(ms)。例如:ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000

    重要

    仅宽表引擎2.7.7及以上版本支持添加超时参数operationTimeout。如何查看或升级当前版本,请参见宽表引擎版本说明升级小版本

    连接示例

    lindorm-cli -url ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test
    
    --添加mysql://协议头连接
    lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test
    
    --指定查询超时时间
    lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000 -username user -password test

    连接成功将返回如下结果:

    Connected to ld-bp187uwcx5f40****-proxy-sql-lindorm-public.lindorm.rds.aliyuncs.com:33060
    lindorm-cli version: 2.0.x

    其中,2.0.x为Lindorm-cli的版本号。

方法二

双击打开Lindorm-cli.exe程序,执行以下语句:

connect <mysql url> <用户名> <密码>

连接示例

connect ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.aliyuncs.com:33060  user test

连接成功无结果返回。

通过Avatica协议连接宽表引擎

客户端部署在Linux或Mac系统

  1. 跳转至Lindorm-cli所在目录。

    cd <Lindorm-cli所在目录>
  2. 执行以下语句连接宽表引擎。

    ./lindorm-cli -url <url> -username <用户名> -password <密码>

    参数说明

    参数

    示例值

    获取方法

    jdbc url

    jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060

    Lindorm宽表引擎的宽表SQL地址

    用户名

    user

    连接Lindorm宽表引擎的用户名

    密码

    test

    连接Lindorm宽表引擎的密码

    重要
    • 如果忘记密码,可以通过Lindorm宽表引擎的集群管理系统修改用户密码

    • 修改密码后,请通过控制台重启引擎。

    连接示例

    ./lindorm-cli -url jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060 -username user -password test

    连接成功将返回以下结果:

    lindorm-cli version: 2.0.xx

    其中,2.0.xx为Lindorm-cli的版本号。

客户端部署在Windows系统

方法一
  1. 打开命令提示符(CMD),跳转至lindorm-cli.exe的所在目录下。

    cd <lindorm-cli.exe所在目录>
  2. 在CMD上执行以下语句连接宽表引擎。

    lindorm-cli -url <jdbc url> -username <用户名> -password <密码>

    参数说明

    参数

    示例值

    获取方法

    jdbc url

    jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060

    Lindorm宽表引擎的宽表SQL地址

    用户名

    user

    连接Lindorm宽表引擎的用户名

    密码

    test

    连接Lindorm宽表引擎的密码

    重要
    • 如果忘记密码,可以通过Lindorm宽表引擎的集群管理系统修改用户密码

    • 修改密码后,请通过控制台重启引擎。

    连接示例

    lindorm-cli -url jdbc:lindorm:table:url=http://ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.aliyuncs.com:30060 -username user -password test

    连接成功将返回如下结果:

    Connected to jdbc:lindorm:table:url=http://ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060
    lindorm-cli version: 2.0.xx

    其中,2.0.xx为Lindorm-cli的版本号。

方法二

双击打开Lindorm-cli.exe程序,执行以下语句:

connect <jdbc url> <用户名> <密码>

连接示例

connect jdbc:lindorm:table:url=http://ld-bp13y790c91f4****-proxy-lindorm-pub.lindorm.aliyuncs.com:30060 user test

连接成功无结果返回。

使用方法

lindorm-cli 同时支持以“交互式”及“非交互式”的模式来执行 SQL 访问宽表引擎。

交互式模式下执行 SQL 的方法

大多数情况下我们都是以交互式模式启动 lindorm-cli 并操作宽表引擎。它的执行流程如下:

  1. 启动 lindorm-cli
    比如通过上一章节【连接方法】中的任一协议连接到 Lindorm 宽表引擎后,客户的终端便会进入 lindorm-cli 的交互界面,并等待用户输入进一步的命令。

    说明

    在 Windows 下直接双击 lindorm-cli.exe 后,Windows 会弹出一个 cmd 终端界面。此时实际上是先启动了 lindorm-cli 的交互式界面,但尚未建立起与 Lindorm 宽表引擎的连接。此时需要通过 connect 子命令建立连接后才能执行后续的 SQL。详见上文的客户端部署在Windows系统中的方法二

  2. 输入 SQL 语句访问宽表引擎
    lindorm-cli 建立好连接进入交互式界面后,用户便可以输入 SQL 访问宽表引擎。宽表引擎支持的 SQL 语句可查阅SQL参考

  3. 退出 lindorm-cli
    在 lindorm-cli 的交互式界面中执行完所要操作的语句后,通过 exit 子命令或者 ctrl+d 快捷键退出 lindorm-cli。

说明

在交互式模式下启动 lindorm-cli 并成功连接宽表引擎后,直到退出该模式前,客户端与宽表引擎始终维持一个连接会话。此期间所有 SQL 操作均在同一会话中执行(但需注意:若会话长时间无操作,系统会自动断开连接以回收资源)。

非交互式模式下执行 SQL 的方法

在编写运维脚本时,若需直接执行Lindorm SQL语句而不进入交互式命令行,可使用lindorm-cli的非交互模式操作宽表引擎。该模式通过命令参数直接运行SQL并返回结果,适用于自动化任务场景,如执行查询或统计操作。

要在 Shell 终端中通过 lindorm-cli 非交互模式执行 SQL 语句,请基于连接方法中的连接参数(如主机地址、端口等),追加 -execute 参数后接单引号或双引号包裹的 SQL 语句,即可快速建立短连接并执行命令。例如:

lindorm-cli -url mysql://ld-xxxxxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password XXXX -execute "CREATE TABLE tb (id VARCHAR, name VARCHAR, address VARCHAR,  PRIMARY KEY(id, name));"

此外,若要导出宽表查询结果至CSV文件,也可通过非交互模式直接执行导出。

重要

导出CSV文件功能需使用 lindorm-cli 2.2.0 或更高版本。查看当前版本方法:

  • 命令行直接查询:执行 lindorm-cli -version 获取版本号

  • 交互模式启动提示:进入交互界面时,初始欢迎信息会显示版本号。

lindorm-cli -url mysql://ld-xxxxxx-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password XXXX -format csv -output ~/result.csv -execute "SELECT * FROM tb;"
说明
  • 短连接机制:在非交互模式下执行每条 SQL 语句时,lindorm-cli 会独立建立连接并在执行结束后立即关闭。

  • 输出控制:执行结果默认输出至终端屏幕(stdout);如需指定重定向的文件路径,请使用 -output 参数。

通过 AI Agent 使用 lindorm-cli

Lindorm-cli 除支持人工交互式和非交互式使用外,也支持被 AI Agent 调用。当希望通过自然语言让 AI Agent 自动完成 Lindorm 数据查询、结果分析或运维脚本生成时,可以结合 Lindorm Agent Skill 与 lindorm-cli 使用。

说明

下文所描述的面向 AI Agent 的能力需要 2.3.0 及以上版本的 lindorm-cli。

适用场景

通过 AI Agent 调用 lindorm-cli 适用于以下场景:

  • 自然语言查询数据:用自然语言描述查询意图,由 Agent 生成并执行 SQL,返回结构化结果。

  • 批量运维脚本生成:让 Agent 根据需求生成调用 lindorm-cli 的脚本,用于定时任务或批量数据处理。

  • 结果结构化导出:通过 Agent 将查询结果直接输出为 JSON/JSONL 等机器可解析格式,供后续程序处理。

安装 Lindorm Agent Skill

Lindorm Agent Skill 为 AI Agent 提供了调用 lindorm-cli 所需的上下文知识,可指导 Agent 自动探测本地 lindorm-cli、选择合适参数并构造命令。

您可以从以下地址下载 Lindorm Agent Skill:alibabacloud-lindorm-agent-skill

安装完成后,Agent 即可在对话中直接调用 lindorm-cli 访问 Lindorm 宽表引擎。Skill 会将下文介绍的 CLI 能力及对应参数默认固化,通常情况下您无需手动输入这些命令行参数。

Agent 使用方式

安装 Lindorm Agent Skill 后,您只需通过自然语言描述需求,Agent 会在 Skill 的指导下自动完成探测、查询、安全控制和凭据注入等操作。

Agent 会自动探测 lindorm-cli 能力

首次调用前,Agent 会先探测当前环境中 lindorm-cli 的版本、支持的协议、输出格式和退出码定义。这让 Agent 能根据实际环境选择正确的调用方式,而不是依赖硬编码假设。

说明

该行为由 Lindorm Agent Skill 内置,对应 lindorm-cli 的 --capabilities 参数。

Agent 会以结构化格式返回结果

Agent 执行查询时,会要求 lindorm-cli 以 JSON 或 JSONL 格式输出结果。stdout 中只包含查询结果数据,状态提示和警告信息会走 stderr,两个流相互隔离,便于 Agent 直接解析。

对于大结果集,Agent 会选择 JSONL 格式逐行消费,避免一次性加载全部数据。

说明

该行为由 Lindorm Agent Skill 内置,对应 lindorm-cli 的 -format json-format jsonl 参数。

Agent 会启用安全护栏

Lindorm Agent Skill 会默认开启安全模式,在客户端拦截 DROP TABLE、TRUNCATE TABLE、DELETE FROM 等高危写操作,防止 Agent 误执行破坏性 SQL。同时,Skill 会限制单次查询返回的最大行数,避免大结果集耗尽 Agent 的上下文窗口。

说明

该行为由 Lindorm Agent Skill 内置,对应 lindorm-cli 的 --safe-mode--max-rows 参数。

Agent 会安全注入凭据

Agent 调用 lindorm-cli 时,Skill 会优先通过环境变量或标准输入注入用户名和密码,避免凭据出现在命令行参数、Shell 历史记录或进程列表中。

说明

该行为由 Lindorm Agent Skill 内置,对应 lindorm-cli 的环境变量凭据注入和 --password-stdin 参数。

命令行参数与子命令

命令行参数

在终端启动 lindorm-cli 的同时,支持同时指定以下命令行参数:

参数名

是否需跟参数值

参数值

详细说明

url

协议名+ lindorm 宽表引擎的 SQL 连接串(含端口)

用于指定 lindorm-cli 连接宽表引擎时所用的协议以及对应的连接串信息。

username

连接所用的用户名

指定的用户名必须是在宽表引擎中事先已经创建好的 Lindorm 用户。

password

用户名对应的密码

-

database

连接的数据库名

默认不指定时连接的是 default 库。如果指定的话,必须要是宽表引擎中已经事先创建好的 database。

execute

要执行的 SQL 语句

指定 execute 参数后,lindorm-cli 将以非交互式模式运行。参数值中指定的 SQL 语句需要用双引号或单引号包裹。

说明

在用双引号引用 SQL 语句时,SQL 中自身的双引号可通过反斜杠\进行转义;但是如果使用单引号引用 SQL 语句,则不具备转义能力。

output

非交互模式下,SQL 执行结果的输出位置

在非交互模式下,output 默认不指定时,SQL 执行结果将被直接输出到标准输出。指定了 output 时,SQL 执行结果将会输出到指定路径下的指定文件;若文件不存在,还会尝试创建文件。

format

以下几种之一:

horizontal, vertical, csv, json, column

改变宽表引擎服务端返回的 SQL 执行结果的格式,默认不指定时实际是 column。

  • column:以常见的表格形式显示结果。

  • horizontal:逐列水平显示数据。

  • vertical:逐行显示数据,将每行数据纵向按列输出。类似 MySQL 命令行中的\G格式。

  • csv: 以 csv 的格式形态显示结果,结果集不再有表格线。

  • json:以JSON的格式形态显示结果。

pretty

-

需要与 format 为 JSON 时一并使用。

打开 pretty 开关时,服务端返回的信息将按 Pretty-printed JSON 的形式输出;默认不指定时,将按压缩形态的 JSON 输出。

csvNoHeader

-

需要与 format 为 CSV 时一并使用。

打开 csvNoHeader 开关时,服务端返回的信息以 CSV 形式输出,不会带上结果集的表头信息(列名)。

nullString

用于替代 NULL 的字符串

需要与 format 为 CSV 时一并使用。

指定 nullString 时,服务端返回的查询结果中包含的 NULL 值将会被指定的字符串替换。

默认不指定nullString 的时候,服务端返回的查询结果中包含的 NULL 值将默认按以下形式输出:

  • 以 MySQL 协议建立连接时,NULL 值用\N表示。

  • 以 Avatica 协议建立连接时,NULL 值用空字符串表示。

version

-

显示 lindorm-cli 的版本信息,此时 lindorm-cli 并不会真正被启动,也不会进入 lindorm-cli 的交互模式。

format

以下几种之一:horizontal, vertical, csv, json, jsonl, column

改变宽表引擎服务端返回的 SQL 执行结果的格式,默认不指定时实际是 column。

  • column:以常见的表格形式显示结果。

  • horizontal:逐列水平显示数据。

  • vertical:逐行显示数据,将每行数据纵向按列输出。

  • csv:以 CSV 的格式形态显示结果,结果集不再有表格线。

  • json:以 JSON 的格式形态显示结果,便于 Agent 解析。

  • jsonl:每行一个独立 JSON 对象,适合 Agent 流式消费大结果集。

capabilities

-

输出 lindorm-cli 的能力声明 JSON,包括支持的引擎、格式、退出码、参数等。AI Agent 场景下由 Lindorm Agent Skill 自动调用,无需手动输入。

safe-mode

-

开启后客户端拦截 DROP TABLE、TRUNCATE TABLE、DELETE FROM 等高危写操作。AI Agent 场景下由 Lindorm Agent Skill 默认开启。

max-rows

正整数

限制客户端返回的最大行数,超出部分会被截断。AI Agent 场景下由 Lindorm Agent Skill 默认设置,避免大结果集耗尽 Agent 上下文窗口。

password-stdin

-

从标准输入读取密码,避免密码出现在命令行参数中。AI Agent 场景下由 Lindorm Agent Skill 优先使用,替代明文 -password 参数。

说明

lindorm-cli 的命令行参数都需要通过短横线 -来指定。

常用子命令

当以交互式模式启动了 lindorm-cli 工具后,除了指示 lindorm-cli向 Lindorm 宽表引擎发送 SQL之外,还可以在交互式界面中输入执行一些 lindorm-cli 自身的子命令来控制 lindorm-cli 的行为。常用的子命令如下所示:

子命令

命令参数

说明

connect

<url> <username> <password>

当 lindorm-cli 只是单纯被启动并进入交互模式时,可以通过 connect 子命令建立起与 Lindorm 宽表引擎的连接。

url, username, password 三个字段的含义同命令行参数的urlusernamepassword

format

以下种类之一:

horizontal, vertical, csv, json

含义同参数 format

help

查看常用子命令集合。

history

查看最近执行的SQL 或子命令。

exit 或 quit

退出 lindorm-cli,断开与 Lindorm 宽表引擎的连接。

常见问题

为什么会连接超时或失败?

连接超时或失败时会报错Failed to connect to <宽表连接地址> connection check failedconnection timeout

可能存在的原因具体如下,请您依次排查:

原因

解决方案

使用公网连接,但未将公网IP地址添加至白名单中。

将客户端公网IP地址添加至Lindorm白名单

查询客户端公网IP地址的方式:在Windows命令提示符(CMD)中输入curl ipinfo.io/ipcurl ifconfig.me

已将公网地址添加至白名单,仍旧连接超时。

可能存在网络环境不稳定等因素,建议您更换为专有网络连接。

使用ECS访问,未将ECS的IP地址添加至Lindorm白名单。

获取ECS的IP地址添加至Lindorm白名单

未使用正确的连接地址。

Lindorm连接地址区分专有网络地址和公网地址,请根据网络环境使用正确的连接地址。

如果以上方案仍无法解决您的问题,请联系Lindorm技术支持(钉钉号:s0s3eg3)。

相关文档