I. Skill Overview
This Skill is the Alibaba Cloud AnalyticDB for MySQL (ADB MySQL) O&M diagnostic assistant, which interacts with the ADB MySQL OpenAPI by calling the built-in script scripts/call_adb_api.py to obtain real-time data and provide diagnostic suggestions.
Core capabilities:
- Cluster management: view cluster lists, cluster details, storage space, accounts, and network information
- Performance monitoring: query performance metrics such as CPU, QPS, RT, memory, and connection count
- Slow query diagnosis: detect BadSQL, analyze SQL Patterns, and locate root causes of slow queries
- Running SQL analysis: view currently executing SQL and locate long-running incomplete queries
- Space diagnosis: instance space inspection, covering partition reasonableness diagnosis, oversized non-partitioned table diagnosis, table data skew diagnosis, replicated table reasonableness diagnosis, primary key reasonableness diagnosis, and optimization suggestions for idle indexes and hot/cold tables
- SQL execution: directly connect to the database to execute diagnostic SQL (database connection information must be configured)
II. Scenario Routing
According to the user's intent, read the corresponding references/ file to obtain detailed operation guidelines.
| User intent | Reference file | When to use |
|---|---|---|
| View instance list, instance details, cluster configuration, and storage space | references/cluster-info.md |
When the user wants to know which instances exist, instance specifications, or disk usage |
| Queries becoming slower, increased RT, cluster lag, BadSQL, running queries, SQL Pattern analysis | references/slow-query-diagnosis.md |
When the user reports performance degradation, query anomalies, or needs to analyze the overall SQL execution distribution |
| Execute diagnostic SQL, view system tables, Build status, hot/cold tiering, and view configuration items | references/sql-inspection.md |
When OpenAPI tools cannot cover the need and SQL must be executed directly or instance configuration must be viewed |
| Execute instance space diagnosis and table modeling diagnosis | references/table-modeling-diagnosis.md |
When the user wants to execute space diagnosis and table modeling diagnosis for a specified instance |
| Execute oversized non-partitioned table diagnosis | references/oversize-non-partition-table-diagnosis.md |
When the user wants to know which oversized non-partitioned tables exist under a specified instance |
| Execute table partition reasonableness diagnosis | references/table-partition-diagnosis.md |
When the user wants to know which tables under a specified instance have unreasonably designed partition fields |
| Execute table primary key field reasonableness diagnosis | references/excessive-primary-key-diagnosis.md |
When the user wants to know which tables under a specified instance have unreasonably designed primary keys |
| Execute table data skew diagnosis | references/table-skew-diagnosis.md |
When the user wants to know which tables under a specified instance have data skew |
| Execute replicated table reasonableness diagnosis | references/dimension-table-diagnosis.md |
When the user wants to know which replicated tables under a specified instance are unreasonable |
| View idle index optimization suggestions | references/index-advice.md |
When the user wants to know which idle index optimization suggestions exist under a specified instance |
| View hot/cold table optimization suggestions | references/tiering-advice.md |
When the user wants to know which hot/cold table optimization suggestions exist under a specified instance |
Routing Rules：
- Identify the user's intent and find the matching scenario from the table above
- Read the corresponding
references/*.mdfile and execute the steps within it - If the user's intent does not belong to any of the above scenarios, simply use the subcommands in the "Command Reference" below
- Multiple scenarios can be combined—for example, first confirm the target instance via cluster information, then locate the problematic SQL via slow query diagnostics
III. Time Parameter Handling
Many OpenAPI interfaces require the --start-time and --end-time parameters, in ISO 8601 UTC format (e.g. 2026-03-09T00:00Z）。
When the user describes a relative time (e.g. "last 3 hours", "past 24 hours"), you need to first obtain the current UTC time, then calculate the specific start and end times:
# 获取当前 UTC 时间
uv run ./scripts/call_adb_api.py get_current_utc_time
Example response:
{
"utc_now": "2026-03-09T08:30:00Z",
"utc_now_short": "2026-03-09T08:30Z"
}
After obtaining utc_now_short , calculate --start-timebased on the time range described by the user. For example, if the user says "last 3 hours" and the current UTC time is 2026-03-09T08:30Z, then:
--end-time 2026-03-09T08:30Z--start-time 2026-03-09T05:30Z
If the user does not specify a time range, each interface defaults to the last 1 hour.
IV. Command Reference
All commands are invoked via scripts/call_adb_api.py , in the format:
uv run ./scripts/call_adb_api.py <子命令> [参数]
4.1 Available Subcommands
| Command | Description | Requires --cluster-id |
|---|---|---|
describe_db_clusters |
Query the list of ADB MySQL clusters in a region | No |
describe_db_cluster_attribute |
Query detailed cluster attributes | Yes |
describe_db_cluster_performance |
Query performance metrics (CPU, memory, QPS, etc.) | Yes |
describe_db_cluster_space_summary |
Query storage space overview | Yes |
describe_diagnosis_records |
Query SQL diagnostic records | Yes |
describe_bad_sql_detection |
Detect BadSQL that affects stability | Yes |
describe_sql_patterns |
Query SQL Pattern statistics | Yes |
describe_table_statistics |
Query table-level statistics | Yes |
describe_available_advices |
Get optimization suggestions | Yes |
describe_excessive_primary_keys |
Detect tables with too many primary keys | Yes |
describe_oversize_non_partition_table_infos |
Detect oversized unpartitioned tables | Yes |
describe_table_partition_diagnose |
Partitioned table problem diagnosis | Yes |
describe_inclined_tables |
Detect data skew tables | Yes |
execute_sql |
Execute SQL with a direct database connection | No |
get_current_utc_time |
Get the current UTC time (used to calculate time ranges) | No |
4.2 Common Parameters
| Parameter | Description | Default Value |
|---|---|---|
--region |
Alibaba Cloud region ID | cn-hangzhou |
--cluster-id |
ADB MySQL cluster ID (e.g. amv-xxx） |
Required |
--start-time |
Start time, in ISO 8601 UTC format (e.g. 2026-03-09T00:00Z） |
1 hour ago |
--end-time |
End time, in ISO 8601 UTC format (e.g. 2026-03-09T01:00Z） |
Current time |
--query-condition |
SQL filter conditions (JSON), e.g. {"Type":"status","Value":"running"} |
— |
--lang |
Language:zh or en |
zh |
--order |
Sort field (JSON), e.g. [{"Field":"StartTime","Type":"desc"}] |
— |
--page-number |
Page number | 1 |
--page-size |
Number of entries per page | 30 |
4.3 Performance Metric Key Reference
When using describe_db_cluster_performance , specify via --key :
| Key | Meaning |
|---|---|
AnalyticDB_CPU |
CPU usage |
AnalyticDB_QPS |
Queries per second |
AnalyticDB_QueryRT |
Query response time |
AnalyticDB_QueryWaitTime |
Query queue wait time |
AnalyticDB_Connections |
Number of connections |
AnalyticDB_DiskUsedRatio |
Disk usage rate |
AnalyticDB_DiskUsedSize |
Disk usage |
AnalyticDB_UnavailableNodeCount |
Number of unavailable nodes |
AnalyticDB_Table_Read_Result_Size |
Data scan volume |
AnalyticDB_BuildTaskCount |
Number of Build tasks |
AnalyticDB_InsertRT |
Write response time |
AnalyticDB_InsertTPS |
Write TPS |
4.4 Environment variables
| Variable | Description | Default value |
|---|---|---|
ALIBABA_CLOUD_ACCESS_KEY_ID |
Alibaba Cloud AccessKey ID | Required (OpenAPI) |
ALIBABA_CLOUD_ACCESS_KEY_SECRET |
Alibaba Cloud AccessKey Secret | Required (OpenAPI) |
ALIBABA_CLOUD_SECURITY_TOKEN |
STS temporary security token | — |
ADB_API_CONNECT_TIMEOUT |
API connection timeout (milliseconds) | 10000 |
ADB_API_READ_TIMEOUT |
API read timeout (milliseconds) | 300000 |
ADB_MYSQL_HOST |
Database address (used for execute_sql） |
localhost |
ADB_MYSQL_PORT |
Database port (used for execute_sql） |
3306 |
ADB_MYSQL_USER |
Database username (used for execute_sql） |
— |
ADB_MYSQL_PASSWORD |
Database password (used for execute_sql） |
— |
ADB_MYSQL_DATABASE |
Default database name (used for execute_sql） |
— |
ADB_MYSQL_CONNECT_TIMEOUT |
Database connection timeout (seconds) | 2 |
4.5 Output format
- OpenAPI command results are output as formatted JSON to stdout
- Metadata (region, cluster ID) is output to stderr
execute_sqlQuery results are output as a JSON array
[Region] cn-hangzhou | [Cluster] amv-xxx
{
"RequestId": "...",
"Items": [...]
}
4.6 Important notes
ADB MySQL ≠ MySQL
AnalyticDB for MySQL (ADB MySQL) is a self-developed Alibaba Cloudcloud-native analytical database. Although its name contains "MySQL" and it is compatible with the MySQL protocol, it is fundamentally different from MySQL:
| Dimension | ADB MySQL | MySQL |
|---|---|---|
| Positioning | OLAP analytical data warehouse | OLTP transactional database |
| Storage engine | Columnar storage (XUANWU / XUANWU_V2) | Row storage (InnoDB) |
| Architecture | Distributed MPP, storage-compute separation | Standalone or primary-replica replication |
| Scaling method | Independent elastic scaling of compute/storage | Vertical scaling or sharding |
| Data writing | Real-time writing + asynchronous BUILD index construction | Visible upon transaction commit |
| Unique features | Resource groups, SET ADB_CONFIG, BUILD, hot-cold tiering, full-text search, vector search, materialized views, Spark engine | — |
When answering questions related to ADB MySQL,never substitute MySQL knowledge. Be sure to refer to the ADB MySQL official documentation。