Cosmos DB for PostgreSQL REST API

  • Article

Azure Cosmos DB for Postgres is a fully managed, cloud-native distributed SQL database for transactional applications.

The Resource Provider Representational State Transfer (REST) APIs enables you to manage your Azure Cosmos DB resources programmatically. Major categories being supported include:

  • Deploy, manage or promote a cluster.
  • Manage coordinator \ worker node configurations.
  • Manage firewall rules.
  • Manage private endpoint connections and private link resources.
  • Manage roles.

Authorization

All Azure Resource Manager REST calls need a valid authorization token in the request header to succeed. See Create the request: Acquire an access token for details on how to get this authorization token.

How to make REST API calls

There are several ways to make REST API calls for any Azure service including Azure Cosmos DB for PostgreSQL. You can use Postman as the most universal all-purpose tool for REST API calls. You can also use curl for some other scenarios including unattended scripts such as the ones used in devops automation. You can also use 'az rest' as an easy way to make REST API calls from Azure CLI.

Placeholders and values

The following information is common to all tasks that you might do using these REST APIs:

  • Replace {api-version} with the latest available API version such as 2022-11-08.
  • Replace {subscriptionId} with your subscription identifier in the URI. This value is a GUID unique to your subscription, such as 6B29FC40-CA47-1067-B31D-00DD010662DA. Locate the subscription ID using the Azure portal subscriptions blade.
  • Replace {resourceGroupName} with the resource group. For more information, see Using Resource groups to manage your Azure resources.
  • Replace {clusterName} with the name of your Azure Cosmos DB for PostgreSQL cluster. Use the short name, such as mydemocluster.
  • Set the Content-Type header to application/json.
  • Set the Authorization header to a JSON Web Token that you obtain from Azure Active Directory. For more information, see Authorization section.

Values

Use the following reference to determine supported values for various REST API calls for Azure Cosmos DB for PostgreSQL clusters and nodes.

Cluster create and update

  • properties.postgresqlVersion: Major PostgreSQL version on all nodes in your cluster. Specify a supported major PostgreSQL version. For example, "15". See the list of supported Postgres versions. Cluster is created with the latest minor PostgreSQL version and the latest corresponding Citus version available in the region selected.
  • properties.citusVersion: Version of Citus extension that is installed on all nodes in your cluster. For example, "11.3". See currently supported Citus version.
    • This property is optional for a new cluster provisioning. If this property is omitted, the latest version of Citus supported for the specified major PostgreSQL version is installed.
    • The primary case for this property is Citus version upgrade such as 11.0 to 11.3. When an updated Citus version is released for the major PostgreSQL version on your cluster, you can use cluster update API call to upgrade only Citus version to the latest one supported for the current major PostgreSQL version.
  • properties.administratorLoginPassword: Password for 'citus' role on all nodes in your cluster. The password needs to meet the following requirements
    • Length: At least 8 characters and at most 128 characters
    • Complexity: Must contain characters from each of the following categories:
      • English uppercase letters
      • English lowercase letters
      • Numbers (0-9)
      • Non-alphanumeric characters (!, $, #, %, etc.)
    • Role name in the password: Can't contain all or parts of the role name. Part of a role name is defined as three or more consecutive alphanumeric characters
  • properties.coordinatorServerEdition: Type of compute in a single node or multi-node cluster's coordinator. Use the following values for the supported single node and multi-node compute
    • Single node
      • Burstable, 1 vCore: BurstableMemoryOptimized
      • Burstable, 2 vCores: BurstableGeneralPurpose
      • Non-burstable, any supported vCores: GeneralPurpose
    • Multi-node
      • Non-burstable, any supported vCores: GeneralPurpose
  • properties.coordinatorVCores: Number of compute vCores in single node or multi-node cluster's coordinator. See supported values on this page.
  • properties.coordinatorStorageQuotaInMb: Storage size in MiB on a single node or on the coordinator in multi-node cluster. See supported storage sizes for single node and multi-node configurations. For instance, to specify 128 GiB of storage use "131072" value (128 GiB * 1024 = 131072 MiB).
  • properties.nodeServerEdition: Type of compute in worker nodes. Only "MemoryOptimized" value is supported.
  • properties.nodeVCores: Number of compute vCores in each worker node in multi-node cluster. See supported values on this page.
  • properties.nodeStorageQuotaInMb: Storage size in MiB on a worker node in a multi-node cluster. See supported storage sizes multi-node configurations. For instance, to specify 2 TiB of storage use "2097152" value (2 TiB * 1024 = 2048 GiB * 1024 = 2097152 MiB).
  • properties.coordinatorEnablePublicIpAccess: When set to "False" this property disables public access to cluster coordinator.
  • properties.nodeEnablePublicIpAccess: The default value for this property is 'false' effectively disabling direct public access to worker nodes. To enable optional direct access to worker nodes in multi-node clusters, you need to set this property to "True" and create firewall rules for those public IP addresses. All firewall rules apply to coordinator and all worker nodes.

Firewall rule create

  • properties.startIpAddress and properties.endIpAddress
    • To create a firewall rule for a single public IP address, specify this IP address as a value for both startIpAddress and endIpAddress.
    • To allow connections from any IP address that is managed by Azure, specify "0.0.0.0" for both startIpAddress and endIpAddress values. Note that this firewall rule would allow connections from the Azure subscriptions of other customers.

Role create

  • properties.password: Password for Postgres role to be created on all nodes in your cluster. The password needs to meet the following requirements
    • Length: At least 8 characters and at most 128 characters
    • Complexity: Must contain characters from each of the following categories:
      • English uppercase letters
      • English lowercase letters
      • Numbers (0-9)
      • Non-alphanumeric characters (!, $, #, %, etc.)
    • Role name in the password: Can't contain all or parts of the role name. Part of a role name is defined as three or more consecutive alphanumeric characters