analyticdb-mysql-cli命令行工具

安装

• 从PyPI安装

  uv tool install analyticdb-mysql-cli

• 从本地源码安装

  cd analyticdb-mysql-cli
  uv tool install .

安装后可使用adbmysql-cli命令，也可使用analyticdb-mysql-cli作为同一程序的别名。

配置连接

支持--dsn命令行参数、ADBMYSQL_DSN环境变量、项目.env文件等方式配置连接，优先级依次递减。

创建全局配置文件连接AnalyticDB for MySQL 集群，命令如下：

mkdir -p ~/.adbmysql
echo 'ADBMYSQL_DSN="mysql://user:pass@host:port/database"' > ~/.adbmysql/config.env

结构化JSON输出

analyticdb-mysql-cli所有命令都返回标准化的JSON结构：

// 成功响应
{
  "ok": true,
  "data": "...",
  "time_ms": 123
}

// 错误响应
{
  "ok": false,
  "error": {
    "code": "SQL_ERROR",
    "message": "详细错误信息"
  }
}

AI Agent 可以通过ok字段即可判断执行结果，无需复杂的文本解析。

查看表列表示例：

analyticdb-mysql-cli schema tables

返回示例：

{
  "ok": true,
  "data": [
    {"name": "e_categories", "columns": 3, "rows": 15},
    {"name": "e_orders", "columns": 6, "rows": 800},
    {"name": "e_order_items", "columns": 5, "rows": 1080},
    {"name": "e_products", "columns": 6, "rows": 50},
    {"name": "e_users", "columns": 6, "rows": 80}
  ],
  "time_ms": 261
}

AI Agent可以直接通过JSON.parse()解析结果，获取表名、列数、行数等信息。

Schema探索

analyticdb-mysql-cli提供完整的Schema探索命令，帮助AI Agent理解数据库结构。

查看表结构：

analyticdb-mysql-cli schema describe e_orders

返回详细的表结构信息，包括列名、类型、索引等，返回示例：

导出DDL：

analyticdb-mysql-cli schema dump

输出所有表的CREATE TABLE语句，方便 AI 理解完整的数据库设计。

数据画像（Table Profile）

table profile命令可以自动分析表的统计特征：

analyticdb-mysql-cli table profile e_orders

返回结果包含：

• 行数统计

• 空值比例

• 唯一值数量

• 取值范围

• 高频值

• 候选关联键

• 时间列

AI Agent可以据此判断应该按什么字段分组、需要处理哪些枚举值等。

关系推断（Relations Infer）

analyticdb-mysql-cli可以自动发现表之间的关联关系：

analyticdb-mysql-cli relations infer

返回示例：

{
  "data": [
    {"from": "e_order_items.order_id", "to": "e_orders.order_id", "confidence": "medium"},
    {"from": "e_order_items.product_id", "to": "e_products.product_id", "confidence": "medium"},
    {"from": "e_orders.user_id", "to": "e_users.user_id", "confidence": "medium"}
  ]
}

AI Agent无需查阅文档或外键约束，即可理解表间JOIN关系，极大地简化了 AI 生成多表 JOIN 查询的难度。例如，AI Agent通过上述返回示例，即可理解：

• 订单明细表通过 order_id 关联订单表

• 订单明细表通过 product_id 关联商品表

• 订单表通过 user_id 关联用户表

多格式输出

analyticdb-mysql-cli支持多种输出格式：

# 表格格式（适合人类阅读）
analyticdb-mysql-cli --format table sql "SELECT * FROM e_users LIMIT 3"

# CSV格式（适合数据导出）
analyticdb-mysql-cli --format csv sql "SELECT * FROM e_users LIMIT 3"

# JSONL格式（适合流式处理）
analyticdb-mysql-cli --format jsonl sql "SELECT * FROM e_users LIMIT 3"

表格格式输出示例：

user_id | username | city | province | register_date | user_level
--------+----------+------+----------+---------------+-----------
     46 | 李敏     | 成都 | 四川     | 2024-05-02    | 银卡
     60 | 陈涛     | 南昌 | 江西     | 2023-12-28    | 银卡
     57 | 李涛     | 厦门 | 福建     | 2023-06-12    | 钻石

行数保护

当查询没有LIMIT子句时，系统自动探测结果集大小。如果超过1001行，将返回LIMIT_REQUIRED错误，避免一次性拉取海量数据导致内存溢出或网络拥塞。

写操作保护

默认情况下，所有SQL都以只读模式执行。执行INSERT、UPDATE、DELETE等写操作需要显式添加--write参数。不带WHERE子句的DELETE/UPDATE会被直接拦截，防止误删全表数据。

敏感信息脱敏

对于phone、email、password、id_card等敏感字段，analyticdb-mysql-cli会自动进行脱敏处理，避免敏感数据泄露。

准备测试表及数据

• 用户表e_users

  CREATE TABLE `e_users` (
    `user_id` int NOT NULL,
    `username` varchar(100) NOT NULL,
    `city` varchar(50) NOT NULL,
    `province` varchar(50) NOT NULL,
    `register_date` date NOT NULL,
    `user_level` varchar(20) NOT NULL,
    KEY `pk_sys_user_id` (`user_id`),
    PRIMARY KEY (`user_id`)
  ) DISTRIBUTE BY HASH(`user_id`) STORAGE_POLICY='HOT' ENGINE='XUANWU_V2';

• 商品分类表e_categories

  CREATE TABLE `e_categories` (
    `category_id` int NOT NULL,
    `category_name` varchar(100) NOT NULL,
    `parent_category_id` int,
    KEY `pk_sys_category_id` (`category_id`),
    PRIMARY KEY (`category_id`)
  ) DISTRIBUTE BY HASH(`category_id`) STORAGE_POLICY='HOT' ENGINE='XUANWU_V2';

• 商品表e_products

  CREATE TABLE `e_products` (
    `product_id` int NOT NULL,
    `product_name` varchar(200) NOT NULL,
    `category_id` int NOT NULL,
    `price` decimal(10, 2) NOT NULL,
    `cost` decimal(10, 2) NOT NULL,
    `created_at` date NOT NULL,
    KEY `pk_sys_product_id` (`product_id`),
    PRIMARY KEY (`product_id`)
  ) DISTRIBUTE BY HASH(`product_id`) STORAGE_POLICY='HOT' ENGINE='XUANWU_V2';

• 订单表e_orders

  CREATE TABLE `e_orders` (
    `order_id` bigint NOT NULL,
    `user_id` int NOT NULL,
    `order_date` date NOT NULL,
    `total_amount` decimal(12, 2) NOT NULL,
    `status` varchar(20) NOT NULL,
    `payment_method` varchar(30) NOT NULL,
    KEY `pk_sys_order_date` (`order_date`),
    KEY `pk_sys_order_id` (`order_id`),
    PRIMARY KEY (`order_id`,`order_date`)
  ) DISTRIBUTE BY HASH(`order_id`) PARTITION BY VALUE(`DATE_FORMAT(order_date, '%Y')`) STORAGE_POLICY='HOT' ENGINE='XUANWU_V2';

• 订单明细表e_order_items

  CREATE TABLE `e_order_items` (
    `item_id` bigint NOT NULL,
    `order_id` bigint NOT NULL,
    `product_id` int NOT NULL,
    `quantity` int NOT NULL,
    `unit_price` decimal(10, 2) NOT NULL,
    KEY `pk_sys_item_id` (`item_id`),
    KEY `pk_sys_order_id` (`order_id`),
    PRIMARY KEY (`order_id`,`item_id`)
  ) DISTRIBUTE BY HASH(`order_id`) STORAGE_POLICY='HOT' ENGINE='XUANWU_V2';

测试数据，请参见ecommerce_demo.sql。

AI Agent分析流程

以“分析销售数据情况”为场景，AI Agent的分析流程如下。

1. 获取表概览

   analyticdb-mysql-cli schema tables
   # 发现有 e_orders、e_order_items、e_products 等 5 张表

2. 查看订单表结构和数据画像

   analyticdb-mysql-cli table profile e_orders
   # 了解到有 800 笔订单，status 有 4 种取值

3. 推断表关系

   analyticdb-mysql-cli relations infer
   # 发现订单与用户、商品的关联关系

4. 执行多维度分析查询

   基于获取的元数据，可以执行以下分析SQL。

   • 整体概况

     analyticdb-mysql-cli sql "SELECT COUNT(*) as total_orders, SUM(total_amount) as total_revenue, AVG(total_amount) as avg_order_value, MIN(order_date) as first_order, MAX(order_date) as last_order FROM e_orders"

   • 订单状态分布

     analyticdb-mysql-cli sql "SELECT status, COUNT(*) as count, SUM(total_amount) as amount FROM e_orders GROUP BY status ORDER BY count DESC"

   • 支付方式分析

     analyticdb-mysql-cli sql "SELECT payment_method, COUNT(*) as count, SUM(total_amount) as amount FROM e_orders GROUP BY payment_method ORDER BY amount DESC"

   • 月度销售趋势

     analyticdb-mysql-cli sql "SELECT DATE_FORMAT(order_date, '%Y-%m') as month, COUNT(*) as orders, SUM(total_amount) as revenue FROM e_orders WHERE status='completed' GROUP BY month ORDER BY month DESC LIMIT 12"

   • 热销商品TOP 10

     analyticdb-mysql-cli sql "SELECT p.product_name, SUM(oi.quantity) as sold_qty, SUM(oi.quantity * oi.unit_price) as revenue FROM e_order_items oi JOIN e_products p ON oi.product_id = p.product_id GROUP BY p.product_id, p.product_name ORDER BY revenue DESC LIMIT 10"

销售数据分析报告

基于上述SQL查询结果，AI Agent自动生成以下分析报告：

整个分析过程中，AI Agent无需人工干预，通过结构化的元数据自主完成了从理解数据结构到执行分析、生成报告的全过程。