clusters

Creates, updates, deletes, gets or lists a clusters resource.

Overview

Name	clusters
Type	Resource
Id	azure.cosmosdb_for_postgresql.clusters

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}".
name	string	The name of the resource.
administratorLogin	string	The administrator's login name of the servers in the cluster.
administratorLoginPassword	string	The password of the administrator login. Required for creation.
authConfig	object	Authentication configuration of a cluster.
citusVersion	string	The Citus extension version on all cluster servers.
coordinatorEnablePublicIpAccess	boolean	If public access is enabled on coordinator.
coordinatorServerEdition	string	The edition of a coordinator server (default: GeneralPurpose). Required for creation.
coordinatorStorageQuotaInMb	integer	The storage of a server in MB. Required for creation. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
coordinatorVCores	integer	The vCores count of a server (max: 96). Required for creation. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
databaseName	string	The database name of the cluster. Only one database per cluster is supported.
earliestRestoreTime	string (date-time)	The earliest restore point time (ISO8601 format) for the cluster.
enableGeoBackup	boolean	If cluster backup is stored in another Azure region in addition to the copy of the backup stored in the cluster's region. Enabled only at the time of cluster creation.
enableHa	boolean	If high availability (HA) is enabled or not for the cluster.
enableShardsOnCoordinator	boolean	If distributed tables are placed on coordinator or not. Should be set to 'true' on single node clusters. Requires shard rebalancing after value is changed.
location	string	The geo-location where the resource lives. Required.
maintenanceWindow	object	Maintenance window of a cluster.
nodeCount	integer	Worker node count of the cluster. When node count is 0, it represents a single node configuration with the ability to create distributed tables on that node. 2 or more worker nodes represent multi-node configuration. Node count value cannot be 1. Required for creation.
nodeEnablePublicIpAccess	boolean	If public access is enabled on worker nodes.
nodeServerEdition	string	The edition of a node server (default: MemoryOptimized).
nodeStorageQuotaInMb	integer	The storage in MB on each worker node. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
nodeVCores	integer	The compute in vCores on each worker node (max: 104). See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
pointInTimeUTC	string (date-time)	Date and time in UTC (ISO8601 format) for cluster restore.
postgresqlVersion	string	The major PostgreSQL version on all cluster servers.
preferredPrimaryZone	string	Preferred primary availability zone (AZ) for all cluster servers.
privateEndpointConnections	array	The private endpoint connections for a cluster.
provisioningState	string	Provisioning state of the cluster.
readReplicas	array	The array of read replica clusters.
serverNames	array	The list of server names in the cluster.
sourceLocation	string	The Azure region of source cluster for read replica clusters.
sourceResourceId	string	The resource id of source cluster for read replica clusters.
state	string	A state of a cluster/server that is visible to user.
systemData	object	Azure Resource Manager metadata containing createdBy and modifiedBy information.
tags	object	Resource tags.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts".

check_name_availability

Name	Datatype	Description
name	string	Name of the cluster.
message	string	Error message.
nameAvailable	boolean	Indicates whether the cluster name is available.
type	string	Type of the cluster.

list_by_resource_group

Name	Datatype	Description
id	string	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}".
name	string	The name of the resource.
administratorLogin	string	The administrator's login name of the servers in the cluster.
administratorLoginPassword	string	The password of the administrator login. Required for creation.
authConfig	object	Authentication configuration of a cluster.
citusVersion	string	The Citus extension version on all cluster servers.
coordinatorEnablePublicIpAccess	boolean	If public access is enabled on coordinator.
coordinatorServerEdition	string	The edition of a coordinator server (default: GeneralPurpose). Required for creation.
coordinatorStorageQuotaInMb	integer	The storage of a server in MB. Required for creation. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
coordinatorVCores	integer	The vCores count of a server (max: 96). Required for creation. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
databaseName	string	The database name of the cluster. Only one database per cluster is supported.
earliestRestoreTime	string (date-time)	The earliest restore point time (ISO8601 format) for the cluster.
enableGeoBackup	boolean	If cluster backup is stored in another Azure region in addition to the copy of the backup stored in the cluster's region. Enabled only at the time of cluster creation.
enableHa	boolean	If high availability (HA) is enabled or not for the cluster.
enableShardsOnCoordinator	boolean	If distributed tables are placed on coordinator or not. Should be set to 'true' on single node clusters. Requires shard rebalancing after value is changed.
location	string	The geo-location where the resource lives. Required.
maintenanceWindow	object	Maintenance window of a cluster.
nodeCount	integer	Worker node count of the cluster. When node count is 0, it represents a single node configuration with the ability to create distributed tables on that node. 2 or more worker nodes represent multi-node configuration. Node count value cannot be 1. Required for creation.
nodeEnablePublicIpAccess	boolean	If public access is enabled on worker nodes.
nodeServerEdition	string	The edition of a node server (default: MemoryOptimized).
nodeStorageQuotaInMb	integer	The storage in MB on each worker node. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
nodeVCores	integer	The compute in vCores on each worker node (max: 104). See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
pointInTimeUTC	string (date-time)	Date and time in UTC (ISO8601 format) for cluster restore.
postgresqlVersion	string	The major PostgreSQL version on all cluster servers.
preferredPrimaryZone	string	Preferred primary availability zone (AZ) for all cluster servers.
privateEndpointConnections	array	The private endpoint connections for a cluster.
provisioningState	string	Provisioning state of the cluster.
readReplicas	array	The array of read replica clusters.
serverNames	array	The list of server names in the cluster.
sourceLocation	string	The Azure region of source cluster for read replica clusters.
sourceResourceId	string	The resource id of source cluster for read replica clusters.
state	string	A state of a cluster/server that is visible to user.
systemData	object	Azure Resource Manager metadata containing createdBy and modifiedBy information.
tags	object	Resource tags.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts".

list

Name	Datatype	Description
id	string	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}".
name	string	The name of the resource.
administratorLogin	string	The administrator's login name of the servers in the cluster.
administratorLoginPassword	string	The password of the administrator login. Required for creation.
authConfig	object	Authentication configuration of a cluster.
citusVersion	string	The Citus extension version on all cluster servers.
coordinatorEnablePublicIpAccess	boolean	If public access is enabled on coordinator.
coordinatorServerEdition	string	The edition of a coordinator server (default: GeneralPurpose). Required for creation.
coordinatorStorageQuotaInMb	integer	The storage of a server in MB. Required for creation. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
coordinatorVCores	integer	The vCores count of a server (max: 96). Required for creation. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
databaseName	string	The database name of the cluster. Only one database per cluster is supported.
earliestRestoreTime	string (date-time)	The earliest restore point time (ISO8601 format) for the cluster.
enableGeoBackup	boolean	If cluster backup is stored in another Azure region in addition to the copy of the backup stored in the cluster's region. Enabled only at the time of cluster creation.
enableHa	boolean	If high availability (HA) is enabled or not for the cluster.
enableShardsOnCoordinator	boolean	If distributed tables are placed on coordinator or not. Should be set to 'true' on single node clusters. Requires shard rebalancing after value is changed.
location	string	The geo-location where the resource lives. Required.
maintenanceWindow	object	Maintenance window of a cluster.
nodeCount	integer	Worker node count of the cluster. When node count is 0, it represents a single node configuration with the ability to create distributed tables on that node. 2 or more worker nodes represent multi-node configuration. Node count value cannot be 1. Required for creation.
nodeEnablePublicIpAccess	boolean	If public access is enabled on worker nodes.
nodeServerEdition	string	The edition of a node server (default: MemoryOptimized).
nodeStorageQuotaInMb	integer	The storage in MB on each worker node. See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
nodeVCores	integer	The compute in vCores on each worker node (max: 104). See https://learn.microsoft.com/azure/cosmos-db/postgresql/resources-compute for more information.
pointInTimeUTC	string (date-time)	Date and time in UTC (ISO8601 format) for cluster restore.
postgresqlVersion	string	The major PostgreSQL version on all cluster servers.
preferredPrimaryZone	string	Preferred primary availability zone (AZ) for all cluster servers.
privateEndpointConnections	array	The private endpoint connections for a cluster.
provisioningState	string	Provisioning state of the cluster.
readReplicas	array	The array of read replica clusters.
serverNames	array	The list of server names in the cluster.
sourceLocation	string	The Azure region of source cluster for read replica clusters.
sourceResourceId	string	The resource id of source cluster for read replica clusters.
state	string	A state of a cluster/server that is visible to user.
systemData	object	Azure Resource Manager metadata containing createdBy and modifiedBy information.
tags	object	Resource tags.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts".

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	resource_group_name, cluster_name, subscription_id		Gets information about a cluster such as compute and storage configuration and cluster lifecycle metadata such as cluster creation date and time.
check_name_availability	select	subscription_id		Checks availability of a cluster name. Cluster names should be globally unique; at least 3 characters and at most 40 characters long; they must only contain lowercase letters, numbers, and hyphens; and must not start or end with a hyphen.
list_by_resource_group	select	resource_group_name, subscription_id		Lists all clusters in a resource group.
list	select	subscription_id		Lists all clusters in a subscription.
create	insert	resource_group_name, cluster_name, subscription_id, location		Creates a new cluster with servers.
update	update	resource_group_name, cluster_name, subscription_id		Updates an existing cluster. The request body can contain one or several properties from the cluster definition.
delete	delete	resource_group_name, cluster_name, subscription_id		Deletes a cluster together with servers in it.
restart	exec	resource_group_name, cluster_name, subscription_id		Restarts all nodes in the cluster.
start	exec	resource_group_name, cluster_name, subscription_id		Starts stopped compute on all cluster nodes.
stop	exec	resource_group_name, cluster_name, subscription_id		Stops compute on all cluster nodes.
promote_read_replica	exec	resource_group_name, cluster_name, subscription_id		Promotes read replica cluster to an independent read-write cluster.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
cluster_name	string	The name of the cluster. Required.
resource_group_name	string	The name of the resource group. The name is case insensitive. Required.
subscription_id	string

SELECT examples

get

Gets information about a cluster such as compute and storage configuration and cluster lifecycle metadata such as cluster creation date and time.

SELECT
id,
name,
administratorLogin,
administratorLoginPassword,
authConfig,
citusVersion,
coordinatorEnablePublicIpAccess,
coordinatorServerEdition,
coordinatorStorageQuotaInMb,
coordinatorVCores,
databaseName,
earliestRestoreTime,
enableGeoBackup,
enableHa,
enableShardsOnCoordinator,
location,
maintenanceWindow,
nodeCount,
nodeEnablePublicIpAccess,
nodeServerEdition,
nodeStorageQuotaInMb,
nodeVCores,
pointInTimeUTC,
postgresqlVersion,
preferredPrimaryZone,
privateEndpointConnections,
provisioningState,
readReplicas,
serverNames,
sourceLocation,
sourceResourceId,
state,
systemData,
tags,
type
FROM azure.cosmosdb_for_postgresql.clusters
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND cluster_name = '{{ cluster_name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
;

check_name_availability

Checks availability of a cluster name. Cluster names should be globally unique; at least 3 characters and at most 40 characters long; they must only contain lowercase letters, numbers, and hyphens; and must not start or end with a hyphen.

SELECT
name,
message,
nameAvailable,
type
FROM azure.cosmosdb_for_postgresql.clusters
WHERE subscription_id = '{{ subscription_id }}' -- required
;

list_by_resource_group

Lists all clusters in a resource group.

SELECT
id,
name,
administratorLogin,
administratorLoginPassword,
authConfig,
citusVersion,
coordinatorEnablePublicIpAccess,
coordinatorServerEdition,
coordinatorStorageQuotaInMb,
coordinatorVCores,
databaseName,
earliestRestoreTime,
enableGeoBackup,
enableHa,
enableShardsOnCoordinator,
location,
maintenanceWindow,
nodeCount,
nodeEnablePublicIpAccess,
nodeServerEdition,
nodeStorageQuotaInMb,
nodeVCores,
pointInTimeUTC,
postgresqlVersion,
preferredPrimaryZone,
privateEndpointConnections,
provisioningState,
readReplicas,
serverNames,
sourceLocation,
sourceResourceId,
state,
systemData,
tags,
type
FROM azure.cosmosdb_for_postgresql.clusters
WHERE resource_group_name = '{{ resource_group_name }}' -- required
AND subscription_id = '{{ subscription_id }}' -- required
;

list

Lists all clusters in a subscription.

SELECT
id,
name,
administratorLogin,
administratorLoginPassword,
authConfig,
citusVersion,
coordinatorEnablePublicIpAccess,
coordinatorServerEdition,
coordinatorStorageQuotaInMb,
coordinatorVCores,
databaseName,
earliestRestoreTime,
enableGeoBackup,
enableHa,
enableShardsOnCoordinator,
location,
maintenanceWindow,
nodeCount,
nodeEnablePublicIpAccess,
nodeServerEdition,
nodeStorageQuotaInMb,
nodeVCores,
pointInTimeUTC,
postgresqlVersion,
preferredPrimaryZone,
privateEndpointConnections,
provisioningState,
readReplicas,
serverNames,
sourceLocation,
sourceResourceId,
state,
systemData,
tags,
type
FROM azure.cosmosdb_for_postgresql.clusters
WHERE subscription_id = '{{ subscription_id }}' -- required
;

INSERT examples

create

Creates a new cluster with servers.

INSERT INTO azure.cosmosdb_for_postgresql.clusters (
tags,
location,
properties,
resource_group_name,
cluster_name,
subscription_id
)
SELECT 
'{{ tags }}',
'{{ location }}' /* required */,
'{{ properties }}',
'{{ resource_group_name }}',
'{{ cluster_name }}',
'{{ subscription_id }}'
RETURNING
id,
name,
location,
properties,
systemData,
tags,
type
;

Manifest

# Description fields are for documentation purposes
- name: clusters
props:
  - name: resource_group_name
    value: "{{ resource_group_name }}"
    description: Required parameter for the clusters resource.
  - name: cluster_name
    value: "{{ cluster_name }}"
    description: Required parameter for the clusters resource.
  - name: subscription_id
    value: "{{ subscription_id }}"
    description: Required parameter for the clusters resource.
  - name: tags
    value: "{{ tags }}"
    description: |
      Resource tags.
  - name: location
    value: "{{ location }}"
    description: |
      The geo-location where the resource lives. Required.
  - name: properties
    value:
      administratorLoginPassword: "{{ administratorLoginPassword }}"
      postgresqlVersion: "{{ postgresqlVersion }}"
      citusVersion: "{{ citusVersion }}"
      maintenanceWindow:
        customWindow: "{{ customWindow }}"
        startHour: {{ startHour }}
        startMinute: {{ startMinute }}
        dayOfWeek: {{ dayOfWeek }}
      preferredPrimaryZone: "{{ preferredPrimaryZone }}"
      enableShardsOnCoordinator: {{ enableShardsOnCoordinator }}
      enableHa: {{ enableHa }}
      coordinatorServerEdition: "{{ coordinatorServerEdition }}"
      coordinatorStorageQuotaInMb: {{ coordinatorStorageQuotaInMb }}
      coordinatorVCores: {{ coordinatorVCores }}
      coordinatorEnablePublicIpAccess: {{ coordinatorEnablePublicIpAccess }}
      nodeServerEdition: "{{ nodeServerEdition }}"
      nodeCount: {{ nodeCount }}
      nodeStorageQuotaInMb: {{ nodeStorageQuotaInMb }}
      nodeVCores: {{ nodeVCores }}
      nodeEnablePublicIpAccess: {{ nodeEnablePublicIpAccess }}
      sourceResourceId: "{{ sourceResourceId }}"
      sourceLocation: "{{ sourceLocation }}"
      pointInTimeUTC: "{{ pointInTimeUTC }}"
      databaseName: "{{ databaseName }}"
      enableGeoBackup: {{ enableGeoBackup }}
      authConfig:
        activeDirectoryAuth: "{{ activeDirectoryAuth }}"
        passwordAuth: "{{ passwordAuth }}"

UPDATE examples

update

Updates an existing cluster. The request body can contain one or several properties from the cluster definition.

UPDATE azure.cosmosdb_for_postgresql.clusters
SET 
tags = '{{ tags }}',
properties = '{{ properties }}'
WHERE 
resource_group_name = '{{ resource_group_name }}' --required
AND cluster_name = '{{ cluster_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
RETURNING
id,
name,
location,
properties,
systemData,
tags,
type;

DELETE examples

delete

Deletes a cluster together with servers in it.

DELETE FROM azure.cosmosdb_for_postgresql.clusters
WHERE resource_group_name = '{{ resource_group_name }}' --required
AND cluster_name = '{{ cluster_name }}' --required
AND subscription_id = '{{ subscription_id }}' --required
;

Lifecycle Methods

restart

Restarts all nodes in the cluster.

EXEC azure.cosmosdb_for_postgresql.clusters.restart 
@resource_group_name='{{ resource_group_name }}' --required, 
@cluster_name='{{ cluster_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

start

Starts stopped compute on all cluster nodes.

EXEC azure.cosmosdb_for_postgresql.clusters.start 
@resource_group_name='{{ resource_group_name }}' --required, 
@cluster_name='{{ cluster_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

stop

Stops compute on all cluster nodes.

EXEC azure.cosmosdb_for_postgresql.clusters.stop 
@resource_group_name='{{ resource_group_name }}' --required, 
@cluster_name='{{ cluster_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required
;

promote_read_replica

Promotes read replica cluster to an independent read-write cluster.

EXEC azure.cosmosdb_for_postgresql.clusters.promote_read_replica 
@resource_group_name='{{ resource_group_name }}' --required, 
@cluster_name='{{ cluster_name }}' --required, 
@subscription_id='{{ subscription_id }}' --required 
@@json=
'{
"enableGeoBackup": {{ enableGeoBackup }}
}'
;