All Products
Search

This Product

    PolarDB:Set whitelists for a cluster

    Document Center

    PolarDB:Set whitelists for a cluster

    Last Updated:Mar 28, 2026

    By default, a new PolarDB for PostgreSQL cluster blocks all external connections. Set IP address whitelists to allow specific clients to connect before creating database accounts.

    Prerequisites

    Before you begin, ensure that you have:

    • A PolarDB for PostgreSQL cluster

    • The internal or public IP addresses of the clients that need access to the cluster

    Limits and considerations

    • The default whitelist named default contains only 127.0.0.1, which blocks all external connections.

    • Setting a whitelist to % or 0.0.0.0/0 allows all IP addresses to connect. Avoid this setting unless strictly necessary, as it compromises database security.

    • PolarDB cannot automatically retrieve internal IP addresses of Elastic Compute Service (ECS) instances in a Virtual Private Cloud (VPC). Add ECS internal IP addresses to a whitelist manually.

    • Each cluster supports up to 50 IP whitelists with a combined total of up to 1,000 IP addresses or CIDR blocks.

    • The following whitelists are created automatically when you use certain Alibaba Cloud services. Do not modify or delete them — doing so prevents the related service from connecting to the cluster.

      Whitelist nameService
      ali_dms_groupData Management Service (DMS)
      hdm_security_ipsDatabase Autonomy Service (DAS)
      dtspolardbData Transmission Service (DTS)
      Warning

      Do not add your application IP addresses to these service-managed whitelists. The related services overwrite these whitelists during updates, which can remove your entries and cause connection failures.

    • To manage whitelist configurations across multiple clusters, use IP whitelist templates. For more information, see Configure a global IP whitelist template.

    Add or modify IP whitelists

    1. Log on to the PolarDB console.

    2. In the upper-left corner, select the region where the cluster is deployed.

    3. Find the cluster and click its ID.

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

    5. On the Whitelists page, do one of the following:

      • Add a whitelist: Click Add IP Whitelist, then specify the whitelist name and the IP addresses allowed to access the cluster.

      • Modify a whitelist: On the right side of a whitelist name, click Modify, then update the IP addresses in the Modify Whitelist panel.

      Whitelist names must meet the following requirements:

      RequirementDetails
      Allowed charactersLowercase letters, digits, and underscores (_)
      Start and endMust start with a letter; must end with a letter or digit
      Length2–120 characters

    6. Click OK.

    What to do next

    After setting whitelists, create a database account and then connect to the cluster:

    Troubleshooting

    Added an ECS IP address but still cannot connect

    The most likely cause is an IP type mismatch. If connecting through an internal endpoint, the whitelist must contain the internal IP address of the ECS instance — not the public IP. If connecting through a public endpoint, add the public IP address instead.

    If the IP type is correct, check whether the ECS instance and the cluster are on the same network:

    • ECS instance is in a classic network: A classic-network ECS instance cannot directly connect to a PolarDB cluster in a VPC. Migrate the ECS instance to the same VPC as the cluster. If the ECS instance must remain in the classic network to reach other classic-network resources, use ClassicLink to connect the classic network to the VPC.

    • ECS instance and cluster are in different VPCs: Purchase a new PolarDB cluster in the same VPC as the ECS instance, or use Cloud Enterprise Network to connect the two VPCs.

    For an internal connection to work, both the ECS instance and the PolarDB cluster must be in the same region and the same VPC.

    Cannot connect through a public endpoint

    First, confirm that the public IP address of your client is in a whitelist. To find your client's public IP, check your network configuration or use an IP lookup service.

    If the IP address looks correct, temporarily set a whitelist to 0.0.0.0/0 and try connecting again. If the connection succeeds, the previously configured public IP address was incorrect. Review and correct it, then remove 0.0.0.0/0. For endpoint details, see View or apply for an endpoint.