All Products
Search

This Product

    ApsaraDB RDS:Manage an ApsaraDB RDS for PostgreSQL instance by using Terraform

    Document Center

    ApsaraDB RDS:Manage an ApsaraDB RDS for PostgreSQL instance by using Terraform

    Last Updated:Aug 26, 2026

    Use Terraform to provision, configure, and destroy an ApsaraDB RDS for PostgreSQL instance without touching the console. This guide covers the full lifecycle: create an instance, update its name, storage, maintenance window, resource group, and availability check mode, then destroy everything when done.

    In this guide, you will:

    • Create an ApsaraDB RDS for PostgreSQL 13 instance with a new virtual private cloud (VPC) and vSwitch

    • Rename the instance

    • Expand storage capacity from 30 GB to 50 GB

    • Enable automatic storage expansion

    • Change the maintenance window

    • Move the instance to a different resource group

    • Change the availability check mode (RDS High-availability Edition only)

    • Destroy all resources when done

    Run every example in this guide with one click in Terraform Explorer.

    Prerequisites

    Before you begin, ensure that you have:

    • A Resource Access Management (RAM) user with an AccessKey pair. Avoid using your Alibaba Cloud root account — if the credentials are leaked, all resources in the account are at risk. See Create a RAM user and Create an AccessKey pair.

    • The RAM user granted the following permissions. Grant only what is needed — excessive permissions create security vulnerabilities (principle of least privilege, PoLP). See Grant permissions to RAM users.

      {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "vpc:DescribeVpcAttribute",
        "vpc:DescribeRouteTableList",
        "vpc:DescribeVSwitchAttributes",
        "vpc:DeleteVpc",
        "vpc:DeleteVSwitch",
        "vpc:CreateVpc",
        "vpc:CreateVSwitch"
      ],
      "Resource": "*"
    },
    {
      "Action": "rds:*",
      "Resource": "*",
      "Effect": "Allow"
    },
    {
      "Action": "dbs:*",
      "Resource": "acs:rds:*:*:*",
      "Effect": "Allow"
    },
    {
      "Action": "hdm:*",
      "Resource": "acs:rds:*:*:*",
      "Effect": "Allow"
    },
    {
      "Action": "dms:LoginDatabase",
      "Resource": "acs:rds:*:*:*",
      "Effect": "Allow"
    },
    {
      "Effect": "Allow",
      "Action": "ram:CreateServiceLinkedRole",
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "ram:ServiceName": [
            "backupencryption.rds.aliyuncs.com"
          ]
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": "bss:ModifyAgreementRecord",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bss:DescribeOrderList",
        "bss:DescribeOrderDetail",
        "bss:PayOrder",
        "bss:CancelOrder"
      ],
      "Resource": "*"
    }
  ]
}

    • A Terraform environment. Choose the option that fits your workflow:

      Option

      Best for

      Terraform Explorer — online runtime, no install needed

      Quick experimentation, no setup cost

      Cloud Shell — Terraform pre-installed, credentials auto-configured

      Fast iteration at low cost

      Local install — full control over your environment

      Custom dev environments or restricted networks

    Terraform resources

    The resources created in this guide are billable. Release them when they are no longer needed.

    All examples use the following Terraform resources:

    Create an RDS instance

    This section creates a PostgreSQL 13 RDS instance using the pg.n2.2c.2m instance type with 30 GB of initial storage.

    1. Create a working directory and a main.tf file inside it. Paste the following configuration:

      • instance_charge_type = "Postpaid" sets pay-as-you-go billing.

      • To create multiple instances with the same configuration, add count = x inside resource "alicloud_db_instance" "instance" {}. To create instances with different configurations, add separate resource "alicloud_db_instance" blocks with distinct names and fields.

      • For all available fields, see ApsaraDB RDS Terraform reference.

      variable "region" {
  default = "cn-hangzhou"
}

provider "alicloud" {
  region = var.region
}

variable "zone_id" {
  default = "cn-hangzhou-b"
}

variable "instance_type" {
  default = "pg.n2.2c.2m"
}

# Create a VPC.
resource "alicloud_vpc" "main" {
  vpc_name   = "alicloud"
  cidr_block = "172.16.0.0/16"
}

# Create a vSwitch.
resource "alicloud_vswitch" "main" {
  vpc_id     = alicloud_vpc.main.id
  cidr_block = "172.16.192.0/20"
  zone_id    = var.zone_id
}

# Create an RDS instance.
resource "alicloud_db_instance" "instance" {
  engine               = "PostgreSQL"
  engine_version       = "13.0"
  instance_type        = var.instance_type
  instance_storage     = "30"
  instance_charge_type = "Postpaid"
  vswitch_id           = alicloud_vswitch.main.id
  # To use an existing VPC and vSwitch instead:
  # vswitch_id         = "vsw-****"
  # To create multiple identical instances, set count to the desired number:
  # count              = x
}

    2. Initialize Terraform:

      terraform init

      Key points: terraform init downloads the Alibaba Cloud provider plugin and sets up the working directory. Run this once per working directory, or again after changing provider or backend configuration. A successful run ends with:

      Initializing the backend...

Initializing provider plugins...
- Checking for available provider plugins...
- Downloading plugin for provider "alicloud" (hashicorp/alicloud) 1.90.1...
...

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

    3. Preview the changes:

      terraform plan

      Key points: terraform plan shows what Terraform will create, modify, or destroy — without making any changes. Review the output before applying.

    4. Apply the configuration:

      terraform apply

      When prompted, type yes and press Enter. The instance takes about 4 minutes to provision. A successful run ends with:

      alicloud_vpc.main: Creating...
alicloud_vpc.main: Creation complete after 7s [id=vpc-****]
alicloud_vswitch.main: Creating...
alicloud_vswitch.main: Creation complete after 6s [id=vsw-****]
alicloud_db_instance.instance: Creating...
alicloud_db_instance.instance: Still creating... [10s elapsed]
...
alicloud_db_instance.instance: Still creating... [2m30s elapsed]
alicloud_db_instance.instance: Creation complete after 4m3s [id=pgm-****]

Apply complete!  Resources: 3 added, 0 changed, 0 destroyed.

    5. Verify that the instance was created.

      Run the terraform show command

      Run the following command to view information about the ApsaraDB RDS for PostgreSQL instance that you created:

      terraform show

      Key fields to confirm:

      # alicloud_db_instance.instance:
resource "alicloud_db_instance" "instance" {
    connection_string          = "pgm-****.pg.rds.aliyuncs.com"
    db_instance_storage_type   = "cloud_essd"
    db_time_zone               = "Asia/Shanghai"
    engine                     = "PostgreSQL"
    engine_version             = "13.0"
    id                         = "pgm-****"
    instance_charge_type       = "Postpaid"
    instance_storage           = 30
    instance_type              = "pg.n2.2c.2m"
    maintain_time              = "18:00Z-22:00Z"
    port                       = "5432"
    security_ips               = [
        "127.0.0.1",
    ]
    tcp_connection_type        = "LONG"
    vpc_id                     = "vpc-****"
    vswitch_id                 = "vsw-****"
    zone_id                    = "cn-hangzhou-j"
}

      You can also view the instance in the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view information about the ApsaraDB RDS for PostgreSQL instance.

      After logging on, you are redirected to the instance list page, where you can view the Instance ID/Name, Running Status, Creation Time, Instance Type, Database Type, Billing Method, Network Type, and Zone of each instance. You can click Create Instance at the top of the page to create a new instance, or filter existing instances by instance ID/name or tag.

    Rename the instance

    Add instance_name to the alicloud_db_instance block to rename the instance to terraformtest.

    1. In main.tf, add the following line to the resource "alicloud_db_instance" "instance" {} block:

      resource "alicloud_db_instance" "instance" {
  ...
+ instance_name    = "terraformtest"
}

    2. Apply the change:

      terraform apply

      Review the execution plan and type yes to confirm:

      # alicloud_db_instance.instance will be updated in-place
~ resource "alicloud_db_instance" "instance" {
      id                         = "pgm-****"
    + instance_name              = "terraformtest"
      # (33 unchanged attributes hidden)
  }

Plan: 0 to add, 1 to change, 0 to destroy.

      A successful run ends with:

      alicloud_db_instance.instance: Modifying... [id=pgm-****]
alicloud_db_instance.instance: Modifications complete after 3s [id=pgm-****]

Apply complete!  Resources: 0 added, 1 changed, 0 destroyed.

    3. Verify the new name.

      Run the terraform show command

      Run the following command to view the name of the ApsaraDB RDS for PostgreSQL instance:

      terraform show

      Confirm instance_name = "terraformtest" appears in the output. You can also check the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view the name of the ApsaraDB RDS for PostgreSQL instance.

      In the Instance ID/Name column of the instance list, you can find the RDS PostgreSQL instance named terraformtest.

    Expand storage capacity

    Change instance_storage to expand the instance's storage from 30 GB to 50 GB.

    1. In main.tf, update instance_storage in the resource "alicloud_db_instance" "instance" {} block:

      resource "alicloud_db_instance" "instance" {
  ...
- instance_storage     = "30"
+ instance_storage     = "50"
}

    2. Apply the change:

      terraform apply

      Review the execution plan and type yes to confirm:

      # alicloud_db_instance.instance will be updated in-place
~ resource "alicloud_db_instance" "instance" {
      id                         = "pgm-****"
    ~ instance_storage           = 30 -> 50
      # (31 unchanged attributes hidden)
  }

Plan: 0 to add, 1 to change, 0 to destroy.

      Storage expansion takes about 4 minutes. A successful run ends with:

      alicloud_db_instance.instance: Modifying... [id=pgm-****]
alicloud_db_instance.instance: Still modifying... [id=pgm-****, 10s elapsed]
...
alicloud_db_instance.instance: Modifications complete after 4m1s [id=pgm-***]

Apply complete!  Resources: 0 added, 1 changed, 0 destroyed.

    3. Verify the updated storage.

      Run the terraform show command

      Run the following command to view the storage capacity of the ApsaraDB RDS for PostgreSQL instance:

      terraform show

      Confirm instance_storage = 50 appears in the output. You can also check the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view the storage capacity of the ApsaraDB RDS for PostgreSQL instance.

      In the Usage Statistics section, view the used and total capacity of Storage Space (for example, 159.00 MB used out of 50 GB total), the status of Automatic Storage Expansion, and the Maximum Storage Expansion Limit. Click Set to configure automatic expansion, or click Expansion History to view historical records.

    Configure automatic storage expansion

    Enable automatic storage expansion so the instance scales up automatically when storage usage exceeds a threshold. This example sets the threshold to 30% and the maximum storage to 100 GB.

    1. In main.tf, add the three following fields to the resource "alicloud_db_instance" "instance" {} block:

      • storage_threshold = "30" triggers expansion when used storage exceeds 30% of total capacity.

      • storage_upper_bound = "100" caps automatic expansion at 100 GB.

      resource "alicloud_db_instance" "instance" {
  ...
+ storage_auto_scale  = "Enable"
+ storage_threshold   = "30"
+ storage_upper_bound = "100"
}

    2. Apply the change:

      terraform apply

      Review the execution plan and type yes to confirm:

      # alicloud_db_instance.instance will be updated in-place
~ resource "alicloud_db_instance" "instance" {
      id                         = "pgm-****"
    + storage_auto_scale         = "Enable"
    ~ storage_threshold          = 0 -> 30
    ~ storage_upper_bound        = 0 -> 100
      # (30 unchanged attributes hidden)
  }

Plan: 0 to add, 1 to change, 0 to destroy.

      This change takes about 6 minutes. A successful run ends with:

      alicloud_db_instance.instance: Modifying... [id=pgm-****]
alicloud_db_instance.instance: Still modifying... [id=pgm-****, 10s elapsed]
...
alicloud_db_instance.instance: Modifications complete after 6m7s [id=pgm-****]

Apply complete!  Resources: 0 added, 1 changed, 0 destroyed.

    3. Verify the configuration.

      Run the terraform show command

      Run the following command to view the automatic storage expansion configurations of the ApsaraDB RDS for PostgreSQL instance:

      terraform show

      Confirm these fields appear in the output:

      storage_auto_scale         = "Enable"
storage_threshold          = 30
storage_upper_bound        = 100

      You can also check the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view the automatic storage expansion configurations of the ApsaraDB RDS for PostgreSQL instance.

      In the Usage Statistics section, confirm that Automatic Storage Expansion is displayed as Enabled, with a maximum storage expansion limit of 100 GB.

    Change the maintenance window

    Change the maintenance window to 13:00–14:00 (UTC+8).

    The ApsaraDB RDS console displays times in UTC+8. Terraform requires UTC. To set a 13:00–14:00 UTC+8 window, use 05:00Z-06:00Z in the configuration.

    1. In main.tf, add maintain_time to the resource "alicloud_db_instance" "instance" {} block:

      resource "alicloud_db_instance" "instance" {
  ...
+ maintain_time    = "05:00Z-06:00Z"
}

    2. Apply the change:

      terraform apply

      Review the execution plan and type yes to confirm:

      # alicloud_db_instance.instance will be updated in-place
~ resource "alicloud_db_instance" "instance" {
      id                         = "pgm-****"
    ~ maintain_time              = "18:00Z-22:00Z" -> "05:00Z-06:00Z"
      # (33 unchanged attributes hidden)
  }

Plan: 0 to add, 1 to change, 0 to destroy.

      A successful run ends with:

      alicloud_db_instance.instance: Modifying... [id=pgm-****]
alicloud_db_instance.instance: Modifications complete after 4s [id=pgm-****]

Apply complete!  Resources: 0 added, 1 changed, 0 destroyed.

    3. Verify the maintenance window.

      Run the terraform show command

      Run the following command to view the maintenance window of the ApsaraDB RDS for PostgreSQL instance:

      terraform show

      Confirm maintain_time = "05:00Z-06:00Z" appears in the output. You can also check the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view the maintenance window of the ApsaraDB RDS for PostgreSQL instance.

      In the Configuration Information section of the instance details page, locate the Maintenance Window field.

    Change the resource group

    Move the RDS instance to a different resource group by setting resource_group_id.

    1. In main.tf, add resource_group_id to the resource "alicloud_db_instance" "instance" {} block:

      resource "alicloud_db_instance" "instance" {
  ...
+ resource_group_id = "rg-****"
}

    2. Apply the change:

      terraform apply

      Review the execution plan and type yes to confirm:

      # alicloud_db_instance.instance will be updated in-place
~ resource "alicloud_db_instance" "instance" {
      id                         = "pgm-****"
    ~ resource_group_id          = "rg-****" -> "rg-****"
      # (33 unchanged attributes hidden)
  }

Plan: 0 to add, 1 to change, 0 to destroy.

      A successful run ends with:

      alicloud_db_instance.instance: Modifying... [id=pgm-****]
alicloud_db_instance.instance: Modifications complete after 4s [id=pgm-****]

Apply complete!  Resources: 0 added, 1 changed, 0 destroyed.

    3. Verify the resource group.

      Run the terraform show command

      Run the following command to view the resource group of the ApsaraDB RDS for PostgreSQL instance:

      terraform show

      Confirm resource_group_id = "rg-****" appears in the output. You can also check the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view the resource group of the ApsaraDB RDS for PostgreSQL instance.

      In the Basic Information section of the instance details page, view the Resource Group ID field.

    Change the availability check mode

    This setting applies only to instances running RDS High-availability Edition.

    Change the availability check mode from long connection (LONG) to short-lived connection (SHORT).

    1. In main.tf, add tcp_connection_type to the resource "alicloud_db_instance" "instance" {} block:

      resource "alicloud_db_instance" "instance" {
  ...
+ tcp_connection_type = "SHORT"
}

    2. Apply the change:

      terraform apply

      Review the execution plan and type yes to confirm:

      # alicloud_db_instance.instance will be updated in-place
~ resource "alicloud_db_instance" "instance" {
      id                         = "pgm-****"
    ~ tcp_connection_type        = "LONG" -> "SHORT"
      # (33 unchanged attributes hidden)
  }

Plan: 0 to add, 1 to change, 0 to destroy.

      A successful run ends with:

      alicloud_db_instance.instance: Modifying... [id=pgm-****]
alicloud_db_instance.instance: Modifications complete after 3s [id=pgm-****]

Apply complete!  Resources: 0 added, 1 changed, 0 destroyed.

    3. Verify the availability check mode.

      Run the terraform show command

      Run the following command to view the availability check method of the ApsaraDB RDS for PostgreSQL instance:

      terraform show

      Confirm tcp_connection_type = "SHORT" appears in the output. You can also check the ApsaraDB RDS console.

      Log on to the ApsaraDB RDS console

      Log on to the ApsaraDB RDS console to view the availability check method of the ApsaraDB RDS for PostgreSQL instance.

      In the Instance Availability section of the instance details page, locate the Availability Check Mode field and confirm that the current value is Short-lived Connection.

    Clean up resources

    When the resources are no longer needed, destroy them to avoid ongoing charges:

    terraform destroy

    For more information, see Common Terraform commands.

    Complete sample code

    Run this sample with one click in Terraform Explorer.
    variable "region" {
  default = "cn-hangzhou"
}

provider "alicloud" {
  region = var.region
}

variable "zone_id" {
  default = "cn-hangzhou-b"
}

variable "instance_type" {
  default = "pg.n2.2c.2m"
}

# Create a VPC.
resource "alicloud_vpc" "main" {
  vpc_name   = "alicloud"
  cidr_block = "172.16.0.0/16"
}

# Create a vSwitch.
resource "alicloud_vswitch" "main" {
  vpc_id     = alicloud_vpc.main.id
  cidr_block = "172.16.192.0/20"
  zone_id    = var.zone_id
}

# Create an RDS instance.
resource "alicloud_db_instance" "instance" {
  engine               = "PostgreSQL"
  engine_version       = "13.0"
  instance_type        = var.instance_type
  instance_storage     = "30"
  instance_charge_type = "Postpaid"
  vswitch_id           = alicloud_vswitch.main.id
  # Rename the instance.
  # instance_name    = "terraformtest"
  # Expand storage to 50 GB.
  # instance_storage = "50"
  # Enable automatic storage expansion.
  # storage_auto_scale  = "Enable"
  # storage_threshold   = "30"
  # storage_upper_bound = "100"
  # Change the maintenance window.
  # maintain_time    = "05:00Z-06:00Z"
  # Move to a different resource group.
  # resource_group_id = "rg-****"
  # Change the availability check mode (RDS High-availability Edition only).
  # tcp_connection_type = "SHORT"
  # To use an existing VPC and vSwitch instead:
  # vswitch_id       = "vsw-****"
  # To create multiple identical instances:
  # count = x
}

    What's next

    • What is Terraform? — Learn the core concepts behind Terraform and how it manages infrastructure as code.

    • Create a Terraform template — Use Resource Orchestration Service (ROS) to manage ApsaraDB RDS resources with Terraform templates, including dependency configuration and parameter management.