DocsICP FilingConsole
Documentation
Home Page ApsaraDB RDS RDS MySQL Database Developer Reference Alibaba Cloud CLI integration example

Alibaba Cloud CLI integration example

Updated at:
Copy as MD
Product
My Favorites

Alibaba Cloud CLI is a general-purpose command-line tool developed based on APIs. Use it to manage RDS instances from your shell instead of the console.

Prerequisites

Before you begin, ensure that you have:

  • An Alibaba Cloud account with access to ApsaraDB RDS

  • A RAM user with the AliyunRDSReadOnlyAccess or AliyunRDSFullAccess policy attached

    Note

    For more information about ApsaraDB RDS access policies, see Use RAM for access control.

  • An AccessKey pair (AccessKey ID and AccessKey secret) for that RAM user

  • A region ID for the region where your RDS instance resides — see Endpoints

Using root account credentials to call API operations poses security risks. Create a dedicated RAM user for API access. See Create a RAM user and Grant permissions to a RAM user.

Install Alibaba Cloud CLI

Install Alibaba Cloud CLI for your operating system:

Alternatively, use Cloud Shell to run Alibaba Cloud CLI commands in your browser without a local installation. See What is Cloud Shell?

Configure Alibaba Cloud CLI

Alibaba Cloud CLI supports several credential types. For most use cases, start with AccessKey credentials.

Credential type When to use Instructions
AccessKey (long-term) Service accounts and automation scripts Steps below
Other credential types Short-term or federated access Credential types

To configure AccessKey credentials:

  1. Create an AccessKey pair for your RAM user and record the AccessKey ID and AccessKey secret. See Create an AccessKey pair for a RAM user.

  2. Use the AccessKey pair to configure identity credentials in the AkProfile configuration profile. For more information, see Configuration example.

  3. (Optional) To run a command in a specific region without changing your default profile, append --region <region-id> to any command. This overrides the region in both the default profile and environment variables. See Command-line options.

Generate a CLI command

Use OpenAPI Explorer to build CLI commands interactively:

  1. Go to the page of the ApsaraDB RDS API.

  2. In the left-side search box, search for the API operation you want to call.

  3. On the Parameters tab, fill in the parameter values.

  4. Click the CLI Example tab to see the generated command with your parameters pre-filled. From the CLI Example tab:

    • Click image to copy the command to your clipboard.

    • Click image to open Cloud Shell and run the command in your browser.

    image

OpenAPI Explorer adds --region to generated commands by default. When present, this option overrides your default profile and environment variable settings. Remove or keep it based on your workflow. For parameter formatting requirements, see Parameter formats.

Call ApsaraDB RDS API operations

Command syntax

All Alibaba Cloud CLI commands follow this structure. See Command structure for details.

aliyun <command> <subcommand> [options and parameters]

Common command options

Option Description
--profile <profileName> Use the specified configuration profile. Overrides the default credential configuration and environment variables.
--region <regionId> Run the command in the specified region. Overrides the default credential configuration and environment variables.
--help Print help information for a command. See Use the help command.

For all available options, see Command-line options.

Example 1: List available API operations

Run --help on the rds command to see all ApsaraDB RDS API operations:

aliyun rds --help

Output:

Alibaba Cloud Command Line Interface Version 3.0.216

Usage:
  aliyun rds <ApiName> --parameter1 value1 --parameter2 value2 ...

Product: Rds (ApsaraDB for RDS)
Version: 2014-08-15

Available Api List:
  ActivateMigrationTargetInstance             Switches workloads over from the source PostgreSQL instance to the destination ApsaraDB RDS for PostgreSQL instance.
  AddTagsToResource                           Adds tags to an instance.
  AllocateInstancePublicConnection            Apply for a public endpoint for an ApsaraDB RDS instance
  AllocateReadWriteSplittingConnection        Applies for a read-only routing endpoint for an instance.
  AttachWhitelistTemplateToInstance           Associates a whitelist template with an instance.
  CalculateDBInstanceWeight                   Queries system-assigned read weights.

...

Browse the full list in List of operations by function.

Example 2: Query instance details

The following command calls DescribeDBInstanceAttribute to retrieve the full configuration of an RDS instance:

aliyun rds DescribeDBInstanceAttribute --region cn-hangzhou --DBInstanceId 'pgm-bp16k272p478****'
Parameter Description Example
--region The region where the instance resides cn-hangzhou
--DBInstanceId The ID of the RDS instance to query pgm-bp16k272p478****

Output:

{
        "Items": {
                "DBInstanceAttribute": [
                        {
                                "AccountMaxQuantity": 99999,
                                "AccountType": "Mix",
                                "AdvancedFeatures": "LinkedServer,DistributeTransaction",
                                "AutoUpgradeMinorVersion": "Auto",
                                "AvailabilityValue": "100.0%",
                                "BabelfishConfig": {},
                                "CanTempUpgrade": false,
                                "Category": "HighAvailability",
                                "ColdDataEnabled": false,
                                "ConnectionMode": "Standard",
                                "ConnectionString": "pgm-bp16k272p478****.pg.rds.aliyuncs.com",
                                "ConsoleVersion": "2",
                                "CreationTime": "2024-08-06T06:18:48Z",
                                "CurrentKernelVersion": "rds_postgres_1400_20240530",
                                "DBClusterNodes": {
                                        "DBClusterNode": []
                                },
                                "DBInstanceCPU": "2",
                                "DBInstanceClass": "pg.n4.2c.2m",
                                "DBInstanceClassType": "x",
                                "DBInstanceDescription": "DB-test",
                                "DBInstanceDiskUsed": 3520069632,
                                "DBInstanceId": "pgm-bp16k272p478****",
                                "DBInstanceMemory": 8192,
                                "DBInstanceNetType": "Intranet",
                                "DBInstanceStatus": "Running",
                                "DBInstanceStorage": 100,
                                "DBInstanceStorageType": "cloud_essd",
                                "DBInstanceType": "Primary",
                                "DBMaxQuantity": 99999,
                                "DedicatedHostGroupId": "",
                                "DeletionProtection": false,
                                "DispenseMode": "MultiAVZDispenseMode",
                                "Engine": "PostgreSQL",
                                "EngineVersion": "14.0",
                                "ExpireTime": "",
                                "Extra": {
                                        "DBInstanceIds": {
                                                "DBInstanceId": []
                                        }
                                },
                                "IPType": "IPv4",
                                "InsId": 1,
                                "InstanceNetworkType": "VPC",
                                "InstructionSetArch": "x86",
                                "IoAccelerationEnabled": "0",
                                "LatestKernelVersion": "rds_postgres_1400_20240530",
                                "LockMode": "Unlock",
                                "MaintainTime": "18:00Z-22:00Z",
                                "MasterZone": "cn-hangzhou-j",
                                "MaxConnections": 800,
                                "MaxIOMBPS": 0,
                                "MaxIOPS": 6800,
                                "OriginConfiguration": "{\"KindCode\":\"18\"}",
                                "PayType": "Postpaid",
                                "Port": "5432",
                                "ProxyType": 2,
                                "ReadOnlyDBInstanceIds": {
                                        "ReadOnlyDBInstanceId": []
                                },
                                "RegionId": "cn-hangzhou",
                                "ResourceGroupId": "rg-acfmz7u4zzrngoa",
                                "SecurityIPList": "0.0.0.0/0,172.16.0.0/12",
                                "SecurityIPMode": "normal",
                                "ServerlessConfig": {},
                                "SlaveZones": {
                                        "SlaveZone": [
                                                {
                                                        "ZoneId": "cn-hangzhou-k"
                                                }
                                        ]
                                },
                                "SuperPermissionMode": "",
                                "SupportCreateSuperAccount": "Yes",
                                "SupportUpgradeAccountType": "Yes",
                                "Tips": "ok",
                                "TipsLevel": 1,
                                "VSwitchId": "vsw-bp1sxxsodv28ey5dl****",
                                "VpcCloudInstanceId": "pgm-bp16k272p478****-20240806141842",
                                "VpcId": "vpc-bp1ov7as4yvz4kxei****",
                                "ZoneId": "cn-hangzhou-j",
                                "kindCode": "18"
                        }
                ]
        },
        "RequestId": "14B99E32-4ECD-5B8E-A9C8-6738C8C95910"
}

Troubleshooting

If an API call returns an error, check that the parameter names and values match the API reference for that operation.

For self-service diagnostics, go to Alibaba Cloud OpenAPI Diagnostics and enter the RequestId from the error response.

What's next

Previous：Python SDK exampleNext：Terraform integration example