All Products
Search

This Product

    PolarDB:Configure a cluster whitelist

    Document Center

    PolarDB:Configure a cluster whitelist

    Last Updated:Jul 14, 2026

    An IP whitelist controls which IP addresses or security groups can access a PolarDB for PostgreSQL (Compatible with Oracle) cluster. After you create a cluster, you must add the IP address of your local environment or an ECS instance to the cluster's whitelist to enable access.

    Precautions

    • PolarDB does not automatically retrieve the internal IP addresses of ECS instances within a VPC. You must manually add the internal IP addresses of the ECS instances that need to access PolarDB.

    • You can create up to 50 IP whitelists. A total of 1,000 IP addresses or CIDR blocks can be added across all whitelists.

    • The system automatically generates groups such as ali_dms_group (the IP whitelist group for DMS), hdm_security_ips (the IP whitelist group for DAS), and dtspolardb (the IP whitelist group for DTS) when you use these products. Do not modify or delete these groups. Modifying or deleting them may affect the functionality of these products.

      Important

      Do not add your business IP addresses to these groups. If you do, product updates might overwrite your IP addresses and disrupt your services.

    • For more information about how to manage global IP whitelists, see Configure a global IP whitelist template.

    Scenarios

    IP whitelists control which IP addresses or security groups can access a PolarDB for PostgreSQL (Compatible with Oracle) cluster. You can configure an IP whitelist to provide a high level of access security for your PolarDB for PostgreSQL (Compatible with Oracle) cluster. You should maintain your whitelists on a regular basis. The following are common scenarios for configuring an IP whitelist:

    • If an ECS instance needs to access a PolarDB for PostgreSQL (Compatible with Oracle) cluster, you must find the IP address of the instance on its Instance Details page and add the IP address to the whitelist.

      Note

      • If the ECS instance and the PolarDB for PostgreSQL (Compatible with Oracle) cluster are in the same VPC, add the private IP address of the ECS instance or the CIDR block of the VPC to the whitelist.

      • If the ECS instance and the PolarDB for PostgreSQL (Compatible with Oracle) cluster are in different VPCs, you can add the public IP address of the ECS instance or its security group to the whitelist. Alternatively, you can migrate the ECS instance to the VPC where the PolarDB for PostgreSQL (Compatible with Oracle) cluster resides. After the migration, you can add the private IP address of the ECS instance or the CIDR block of the VPC to the whitelist.

    • If a local server, computer, or another cloud server needs to access a PolarDB cluster, you must add its public IP address to the whitelist.

    Configure an IP whitelist

    1. Log on to the PolarDB console. In the navigation pane on the left, click Clusters. Select the region where the cluster is located, and then click the cluster ID to go to the cluster details page.

    2. In the left-side navigation pane, choose Settings and Management > Whitelists.

    3. On the Cluster Whitelist page, you can click Add Whitelist to create a whitelist group or click Configure to modify an existing whitelist group.

      • To add an IP whitelist group:

        Click Add Whitelist. In the Add Whitelist dialog box, enter a name for the group and add IP addresses to the whitelist.

      • To modify an IP whitelist group:

        Click Configure next to the name of the IP whitelist group that you want to modify. In the Configure Whitelist dialog box, add IP addresses to the whitelist.

      Note

      • An IP whitelist group name must meet the following requirements:

        • It must consist of lowercase letters, digits, and underscores (_).

        • It must start with a letter and end with a letter or digit.

        • It must be 2 to 120 characters in length.

      • IP address whitelist:

        • You can enter IP addresses, such as 192.168.0.1, or CIDR blocks, such as 192.168.0.0/24.

        • Separate multiple IP addresses or CIDR blocks with commas (,). For example, 192.168.0.1,192.168.0.0/24.

        • 127.0.0.1 denies access from any IP address.

        • If you set the whitelist to 0.0.0.0/0, access from any IP address is allowed. This setting significantly reduces the security of your database. We recommend that you do not use this setting unless it is necessary.

      • Each cluster includes a default IP whitelist group named default. This group contains the IP address 127.0.0.1, which means that no IP address can access the cluster by default.

    Next steps

    After you configure the cluster whitelist and create a database account, you can connect to the database cluster to manage your database.

    FAQ

    • Access is denied even after you have added the IP address of an ECS instance to the IP address whitelist.

      Answer:

      1. Check whether the IP addresses in the whitelist are correct. If you access the cluster over an internal network, you must add the private IP address of the ECS instance. If you access the cluster over the Internet, you must add the public IP address of the ECS instance.

      2. Check whether the ECS instance and the PolarDB cluster are deployed in the same network type. If the ECS instance is deployed in a classic network, you can migrate the ECS instance to the virtual private cloud (VPC) where the PolarDB cluster is located. For more information, see Migrate from a classic network to a VPC.

        Note

        Do not migrate the ECS instance if it needs to access other resources in the classic network. This is because after the migration, the instance can no longer access the classic network.

        Alternatively, you can use ClassicLink to connect a classic network to a virtual private cloud (VPC).

      3. Confirm whether the ECS instance and the cluster are in the same VPC. If they are not, you can purchase a new PolarDB cluster in the same VPC as the ECS instance, or connect the two VPCs using Cloud Enterprise Network to enable access.

    • Why does my public network connection fail?

      Answer:

      1. If you use an ECS instance to access the cluster over the Internet, make sure that you have added the public IP address of the ECS instance to the whitelist, not its private IP address.

      2. Set the IP whitelist to 0.0.0.0/0 and try to connect again. If the connection is successful, the public IP address that you previously added to the whitelist was incorrect. For more information about how to find the correct public IP address, see View or request an endpoint.

    • How do I connect over an internal network?

      Answer: To connect to a PolarDB cluster from an ECS instance over an internal network, the following conditions must be met:

      • The instance and cluster are in the same region.

      • The instance and cluster have the same network type. If the network type is VPC, they must be in the same VPC.

      • The internal IP address of the ECS instance is added to the IP whitelist of the PolarDB cluster.