Use Lindorm-cli to connect to the wide table engine - Lindorm

Lindorm-cli is a simple command line interface provided by Lindorm to connect to and manage Lindorm databases. You can use Lindorm-cli to perform basic SQL operations, such as creating tables, querying data, writing data, and exporting data. This topic describes how to use Lindorm-cli to connect to and use Lindorm LindormTable.

Prerequisites

The IP address of the client must be added to the whitelist of the Lindorm instance. For more information, see Configure whitelists.

Network types

You can use the following network types to connect to LindormTable.

Network type	Description
Virtual private cloud (VPC) (Recommended)	A virtual private cloud (VPC) is a private network that is dedicated to your Alibaba Cloud account. VPCs are logically isolated from each other to provide high security. When Lindorm-cli is deployed on an ECS instance, you can use Lindorm-cli to connect to LindormTable over a VPC. This ensures high security and reduces network latency.
Internet	If you want to use an on-premises device to test or manage LindormTable, you can deploy Lindorm-cli on the device and connect the device to LindormTable over the Internet. Note You are not charged for Traffic that is generated when you access LindormTable over the Internet. However, the connection may be exposed to security risks. We recommend that you use a VPC to connect to LindormTable to ensure security. To use the public endpoint to connect to LindormTable, you must enable the public endpoint in the console. For more information about how to enable the public endpoint, see the Procedure section of the "View endpoints" topic.

Connect using the MySQL protocol (Recommended)

Step 1: Install Lindorm-cli

Download the Lindorm-cli installation package for your operating system. The following table provides the download links.

Note

You can use the SHA256 checksum in the following table to verify the integrity and authenticity of the downloaded Lindorm-cli installation package.

Operating system	Download link	SHA256 checksum
Linux	lindorm-cli for linux You can also run the following command to download the package: `wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-latest.tar.gz`	21945c466e2de2c256edd16afdfbb2234301573feb649a673939471a3d882b1a
Linux-arm64	lindorm-cli for linux-arm64 You can also run the following command to download the package: `wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-arm64-latest.tar.gz`	bcae4d8479201d69e4883105d1a7f933fa46d78e19c171e8e1ebfbee28f6d953
Mac (Intel chip)	lindorm-cli for mac	e82cb1678ea5b263813ccb87fff0149526c36a2654082785efe5a6aaeb4eb24b
Mac (Arm chip)	lindorm-cli for mac	538d5fef122b416ca2ab63fd7074b77ef25840e9feb8d3490405aae36a537a68
Windows	lindorm-cli for windows-x64	e61078108a72b85382363e9619b8820aa5245bad60dec79ffd4bf9fea976e280

Decompress the Lindorm-cli package.
For example, on a Linux operating system, run the following command to decompress the package. After the package is decompressed, you can find the lindorm-cli file.
```
tar zxvf lindorm-cli-linux-latest.tar.gz
```

Step 2: Connect to LindormTable

Important

Only Lindorm-cli V2.0.0 or later supports connections to LindormTable using the MySQL protocol.

Clients deployed on Linux or macOS

Navigate to the directory where Lindorm-cli is located.
```
cd <Directory where Lindorm-cli is located>
```

Run the following statement to connect to LindormTable.

./lindorm-cli -url <mysql url> -username <Username> -password <Password>

Parameters

Parameter	Description
mysql url	The MySQL-compatible endpoint of LindormTable. For more information about connection configurations, see Connection settings.
Username	The username that is used to connect to LindormTable.
Password	The password that is used to connect to LindormTable. Important If you forget the password, you can change the user password in the cluster management system of LindormTable. After you change the password, restart the DPI engine in the console.

Connection settings

Supported connection setting

Description

mysql:// protocol header

You can add the mysql:// protocol header before the mysql url.

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

Custom connection parameters on the server side

You can set custom connection parameters on the server side after the mysql url in the key1=value1&key2=value2 format.

The following parameter is supported:

operationTimeout: specifies the query timeout duration. Format: <mysql url>?operationTimeout=<Timeout duration>. The timeout duration is measured in milliseconds (ms). Example: ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000.

Important

The operationTimeout parameter can be added only in LindormTable V2.7.7 or later. For more information about how to view or upgrade the current version, see LindormTable version guide and Minor version update.

Examples

./lindorm-cli -url ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Connect to the instance by adding the mysql:// protocol header.
./lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Specify the query timeout duration.
./lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000 -username user -password test

If the connection is successful, the following output is returned:

lindorm-cli version: 2.0.x

In the output, 2.0.x indicates the version number of Lindorm-cli.

Clients deployed on Windows

Method 1

Open the command prompt (CMD) and navigate to the directory where lindorm-cli.exe is located.
```
cd <Directory where lindorm-cli.exe is located>
```

Run the following statement in the CMD to connect to LindormTable.

lindorm-cli -url <mysql url> -username <Username> -password <Password>

Parameters

Parameter	Example	How to obtain
mysql url	ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060	The MySQL-compatible endpoint of LindormTable. For more information about connection configurations, see Connection settings.
Username	user	The username that is used to connect to LindormTable.
Password	test	The password that is used to connect to LindormTable. Important If you forget the password, you can change the user password in the cluster management system of LindormTable. After you change the password, restart the DPI engine in the console.

Connection settings

Supported connection setting

Description

mysql:// protocol header

You can add the mysql:// protocol header before the mysql url.

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

Custom connection parameters on the server side

You can set custom connection parameters on the server side after the mysql url in the key1=value1&key2=value2 format.

The following parameter is supported:

Important

Examples

lindorm-cli -url ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Connect to the instance by adding the mysql:// protocol header.
lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060 -username user -password test

--Specify the query timeout duration.
lindorm-cli -url mysql://ld-bp187uwcx5f40****-proxy-lindorm-vpc.lindorm.aliyuncs.com:33060?operationTimeout=120000 -username user -password test

If the connection is successful, the following output is returned:

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

In the output, 2.0.x indicates the version number of Lindorm-cli.

Method 2

Double-click the lindorm-cli.exe program and run the following statement:

connect <mysql url> <Username> <Password>

Example

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

If the connection is successful, no output is returned.

Step 3: Use LindormTable

Create a database

Run the following statement to create a database named test.
```
CREATE DATABASE test; 
```
Run the following statement to use the test database.
```
USE test; 
```

Create a table

Create a data table named tb in the test database.

CREATE TABLE tb (id VARCHAR, name VARCHAR, address VARCHAR,  PRIMARY KEY(id, name)) ;

Write data

UPSERT INTO tb (id, name, address) VALUES ('001', 'jack',  'hz');

Query data

Data can be output in multiple formats, such as table output, CSV format output, and vertical column output for each row. You can run the format command to customize the data output format. After you change the output format, the data that you query using the SELECT statement is displayed in the specified format. If you do not specify an output format, the data is displayed in a table by default.

Important

The format command is supported only in the Lindorm-cli tool.

Specify to output returned data as a table (default)

The following is a sample search statement:

format table;
SELECT * FROM tb;

This statement has the same effect as the following statement:

SELECT * FROM tb;

The following output is returned:

+-----+-------+---------+
| id  | name  | address |
+-----+-------+---------+
| 001 | jack  | hz      |
+-----+-------+---------+

CSV Format Outputs

format csv;
SELECT * FROM tb;

The following output is returned:

id,name,address
001,jack,hz

Vertical output of each row

format vertical;
SELECT * FROM tb;

The following output is returned:

********************* 1. row *********************
id:      001
name:    jack
address: hz

Connect using the Avatica protocol

Step 1: Install Lindorm-cli

Download the Lindorm-cli installation package for your operating system. The following table provides the download links.

Note

You can use the SHA256 checksum in the following table to verify the integrity and authenticity of the downloaded Lindorm-cli installation package.

Operating system	Download link	SHA256 checksum
Linux	lindorm-cli for linux You can also run the following command to download the package: `wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-latest.tar.gz`	21945c466e2de2c256edd16afdfbb2234301573feb649a673939471a3d882b1a
Linux-arm64	lindorm-cli for linux-arm64 You can also run the following command to download the package: `wget https://tsdbtools.oss-cn-hangzhou.aliyuncs.com/lindorm-cli-linux-arm64-latest.tar.gz`	bcae4d8479201d69e4883105d1a7f933fa46d78e19c171e8e1ebfbee28f6d953
Mac (Intel chip)	lindorm-cli for mac	e82cb1678ea5b263813ccb87fff0149526c36a2654082785efe5a6aaeb4eb24b
Mac (Arm chip)	lindorm-cli for mac	538d5fef122b416ca2ab63fd7074b77ef25840e9feb8d3490405aae36a537a68
Windows	lindorm-cli for windows-x64	e61078108a72b85382363e9619b8820aa5245bad60dec79ffd4bf9fea976e280

Decompress the Lindorm-cli package.
For example, on a Linux operating system, run the following command to decompress the package. After the package is decompressed, you can find the lindorm-cli file.
```
tar zxvf lindorm-cli-linux-latest.tar.gz
```

Step 2: Connect to LindormTable

Clients deployed on Linux or macOS

Navigate to the directory where Lindorm-cli is located.
```
cd <Directory where Lindorm-cli is located>
```

Run the following statement to connect to LindormTable.

./lindorm-cli -url <url> -username <Username> -password <Password>

Parameters

Parameter	Example	How to obtain
jdbc url	jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060	The SQL endpoint of LindormTable.
Username	user	The username that is used to connect to LindormTable.
Password	test	The password that is used to connect to LindormTable. Important If you forget the password, you can change the user password in the cluster management system of LindormTable. After you change the password, restart the DPI engine in the console.

Example

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

A successful connection returns the following result:

lindorm-cli version: 2.0.xx

In the output, 2.0.xx represents the version number of Lindorm-cli.

Clients deployed in Windows

Method 1

Open the command prompt (CMD) and navigate to the directory where lindorm-cli.exe is located.
```
cd <Directory where lindorm-cli.exe is located>
```

Run the following statement in the CMD to connect to LindormTable.

lindorm-cli -url <jdbc url> -username <Username> -password <Password>

Parameters

Parameter	Example	How to obtain
jdbc url	jdbc:lindorm:table:url=http://ld-bp17j28j2y7pm****-proxy-lindorm-pub.lindorm.rds.aliyuncs.com:30060	The SQL endpoint of LindormTable.
Username	user	The username that is used to connect to LindormTable.
Password	test	The password that is used to connect to LindormTable. Important If you forget the password, you can change the user password in the cluster management system of LindormTable. After you change the password, restart the DPI engine in the console.

Example

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

A successful connection returns the following result:

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

In the returned result, 2.0.xx indicates the version number of Lindorm-cli.

Method 2

Double-click the lindorm-cli.exe program and run the following statement:

connect <jdbc url> <Username> <Password>

Example

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

A successful connection returns no result.

Step 3: Use LindormTable

Create a database

Run the following statement to create a database named test.
```
CREATE DATABASE test; 
```
Run the following statement to use the test database.
```
USE test; 
```

Create a table

Create a data table named tb in the test database.

CREATE TABLE tb (id VARCHAR, name VARCHAR, address VARCHAR,  PRIMARY KEY(id, name)) ;

Write data

UPSERT INTO tb (id, name, address) VALUES ('001', 'jack',  'hz');

Query data

Important

The format command is supported only in the Lindorm-cli tool.

Specify to output returned data as a table (default)

The following is a sample search statement:

format table;
SELECT * FROM tb;

This statement has the same effect as the following statement:

SELECT * FROM tb;

The following output is returned:

+-----+-------+---------+
| id  | name  | address |
+-----+-------+---------+
| 001 | jack  | hz      |
+-----+-------+---------+

CSV Format Outputs

format csv;
SELECT * FROM tb;

The following output is returned:

id,name,address
001,jack,hz

Vertical output of each row

format vertical;
SELECT * FROM tb;

The following output is returned:

********************* 1. row *********************
id:      001
name:    jack
address: hz

Common Lindorm-cli commands

!help: Displays help commands.
!connect: Connects to a server.
exit, quit, or Ctrl+D: Exits the current connection.

FAQ

Why does the connection time out or fail?

If a connection times out or fails, an error message such as Failed to connect to <LindormTable endpoint> connection check failed or connection timeout is reported.

The following table describes possible causes and their solutions. We recommend that you check them in order.

Cause	Solution
You are connecting to the instance over the Internet, but the public IP address of the client is not in the whitelist.	Add the public IP address of the client to the Lindorm whitelist. You can retrieve the public IP address of your client in one of the following ways: In the Windows command prompt (CMD), run `curl ipinfo.io/ip` or `curl ifconfig.me`. On your on-premises device, visit the IP query website.
The public IP address is in the whitelist, but the connection still times out.	This issue may be caused by an unstable network. We recommend that you use a VPC connection.
You are using an ECS instance for access, but the IP address of the ECS instance is not in the Lindorm whitelist.	Obtain the IP address of the ECS instance and add the IP address to the Lindorm whitelist.
An incorrect connection address is used.	Lindorm provides VPC and public endpoints. Use the correct endpoint for your network type.

If the issue persists, contact Lindorm technical support on DingTalk at s0s3eg3.

References

For more information about the SQL syntax of LindormTable, see SQL reference.
For information about other connection methods, see Connect to and use the wide table engine using the MySQL command line and Use the MySQL protocol (Recommended).