Clusters - Create Or Replace

Creates a new HorizonDB cluster or replaces an existing cluster. PointInTimeRestore creates the new Cluster resource and hydrates its service-owned database storage from an available source backup. It does not clone source pools, Pool-scoped endpoints, firewall rules, parameter-group associations, or other child resources. The new Cluster receives its service-generated Cluster-scoped Endpoint named cluster. For restore, postgreSqlVersion must be omitted because the service obtains it from backup metadata. During restore creation, the service ignores the requested backup.geoRedundancy value and configures the new cluster with the same geo-redundancy setting as the source cluster; this applies to both same-location and cross-location restores. All remaining new-cluster configuration comes from the request or service defaults. Same-location restore requires and honors pointInTimeUtc and allows creationSourceClusterLocation to be omitted. Cross-location restore requires creationSourceClusterLocation to identify the source cluster's Azure location and requires pointInTimeUtc, but ignores the supplied timestamp and restores the latest available backup. Cross-location responses omit pointInTimeUtc.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.HorizonDb/clusters/{clusterName}?api-version=2026-10-01-preview

URI Parameters

Name In Required Type Description
clusterName
path True

string

minLength: 1
maxLength: 63
pattern: ^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$

The name of the HorizonDB cluster.

resourceGroupName
path True

string

minLength: 1
maxLength: 90

The name of the resource group. The name is case insensitive.

subscriptionId
path True

string (uuid)

The ID of the target subscription. The value must be an UUID.

api-version
query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Required Type Description
location True

string

The geo-location where the resource lives

identity

HorizonDbClusterManagedServiceIdentity

The managed service identities assigned to this resource. Omitting the entire identity property from PUT or PATCH preserves all current assignments. When provided, PUT replaces the user-assigned identity set and PATCH merges it; null PATCH dictionary entries remove individual identities. Setting type to None clears all assignments.

properties

ClusterProperties

The resource-specific properties for this resource.

tags

object

Resource tags.

Responses

Name Type Description
200 OK

Cluster

The response returned when an asynchronous HorizonDB cluster replacement is accepted.

Headers

  • Azure-AsyncOperation: string
  • Retry-After: integer
201 Created

Cluster

The response returned when asynchronous HorizonDB cluster creation is accepted.

Headers

  • Azure-AsyncOperation: string
  • Retry-After: integer
Other Status Codes

ErrorResponse

An unexpected error response.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Create a HorizonDB cluster with customer-managed key data encryption
Create a PostgreSQL 18 HorizonDB cluster with minimum configuration and service defaults
Create or replace a HorizonDB cluster
Restore a HorizonDB cluster across Azure regions from the latest available backup
Restore a HorizonDB cluster to a point in time

Create a HorizonDB cluster with customer-managed key data encryption

Sample request

PUT https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster?api-version=2026-10-01-preview

{
  "location": "eastus2",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/primary-encryption-identity": {}
    }
  },
  "properties": {
    "postgreSqlVersion": "17",
    "backup": {
      "geoRedundancy": "Disabled",
      "retentionDays": 14
    },
    "dataEncryption": {
      "type": "AzureKeyVault",
      "primaryKeyUri": "https://primary-key-vault.vault.azure.net/keys/horizondb-primary-key",
      "primaryUserAssignedIdentityId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/primary-encryption-identity"
    }
  }
}

Sample response

Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/11111111-1111-1111-1111-111111111111?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster",
  "name": "example-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/primary-encryption-identity": {
        "principalId": "11111111-1111-1111-1111-111111111111",
        "clientId": "22222222-2222-2222-2222-222222222222"
      }
    }
  },
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "Create",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Disabled",
      "retentionDays": 14
    },
    "dataEncryption": {
      "type": "AzureKeyVault",
      "primaryKeyUri": "https://primary-key-vault.vault.azure.net/keys/horizondb-primary-key",
      "primaryUserAssignedIdentityId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/primary-encryption-identity",
      "primaryEncryptionKeyStatus": "Valid",
      "primaryEncryptionKeyCurrentVersion": "33333333333333333333333333333333"
    },
    "state": "Updating",
    "provisioningState": "InProgress",
    "readWritePool": {}
  }
}
Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/11111111-1111-1111-1111-111111111111?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster",
  "name": "example-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/primary-encryption-identity": {
        "principalId": "11111111-1111-1111-1111-111111111111",
        "clientId": "22222222-2222-2222-2222-222222222222"
      }
    }
  },
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "Create",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Disabled",
      "retentionDays": 14
    },
    "dataEncryption": {
      "type": "AzureKeyVault",
      "primaryKeyUri": "https://primary-key-vault.vault.azure.net/keys/horizondb-primary-key",
      "primaryUserAssignedIdentityId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/primary-encryption-identity",
      "primaryEncryptionKeyStatus": "Valid",
      "primaryEncryptionKeyCurrentVersion": "33333333333333333333333333333333"
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}

Create a PostgreSQL 18 HorizonDB cluster with minimum configuration and service defaults

Sample request

PUT https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/minimum-defaults?api-version=2026-10-01-preview

{
  "location": "eastus2",
  "properties": {
    "postgreSqlVersion": "18",
    "backup": {
      "geoRedundancy": "Disabled"
    }
  }
}

Sample response

Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/55555555-5555-5555-5555-555555555555?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/minimum-defaults",
  "name": "minimum-defaults",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "properties": {
    "postgreSqlVersion": "18",
    "creationMode": "Create",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Disabled",
      "retentionDays": 7
    },
    "state": "Updating",
    "provisioningState": "InProgress",
    "readWritePool": {}
  }
}
Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/55555555-5555-5555-5555-555555555555?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/minimum-defaults",
  "name": "minimum-defaults",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "properties": {
    "postgreSqlVersion": "18",
    "creationMode": "Create",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Disabled",
      "retentionDays": 7
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}

Create or replace a HorizonDB cluster

Sample request

PUT https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster?api-version=2026-10-01-preview

{
  "location": "eastus2",
  "tags": {
    "environment": "production"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/fabric-writer": {}
    }
  },
  "properties": {
    "postgreSqlVersion": "17",
    "network": {
      "publicAccess": "Enabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    }
  }
}

Sample response

Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/44444444-4444-4444-4444-444444444444?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster",
  "name": "example-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "tags": {
    "environment": "production"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/fabric-writer": {
        "principalId": "11111111-1111-1111-1111-111111111111",
        "clientId": "22222222-2222-2222-2222-222222222222"
      }
    }
  },
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "Create",
    "network": {
      "publicAccess": "Enabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14,
      "earliestRestorePointUtc": "2026-07-27T02:00:00Z"
    },
    "state": "Updating",
    "provisioningState": "InProgress",
    "readWritePool": {
      "designatedPoolResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster/pools/example-pool-01"
    }
  }
}
Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/11111111-1111-1111-1111-111111111111?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/example-cluster",
  "name": "example-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "tags": {
    "environment": "production"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/identity-resource-group/providers/Microsoft.ManagedIdentity/userAssignedIdentities/fabric-writer": {
        "principalId": "11111111-1111-1111-1111-111111111111",
        "clientId": "22222222-2222-2222-2222-222222222222"
      }
    }
  },
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "Create",
    "network": {
      "publicAccess": "Enabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14,
      "earliestRestorePointUtc": "2026-07-27T02:00:00Z"
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}

Restore a HorizonDB cluster across Azure regions from the latest available backup

Sample request

PUT https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/cross-region-restored-cluster?api-version=2026-10-01-preview

{
  "location": "westus2",
  "properties": {
    "creationMode": "PointInTimeRestore",
    "pointInTimeUtc": "2026-07-27T12:00:00Z",
    "creationSourceClusterResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/source-cluster",
    "creationSourceClusterLocation": "eastus2",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    }
  }
}

Sample response

Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/westus2/operationStatuses/44444444-4444-4444-4444-444444444444?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/cross-region-restored-cluster",
  "name": "cross-region-restored-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "westus2",
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "PointInTimeRestore",
    "creationSourceClusterResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/source-cluster",
    "creationSourceClusterLocation": "eastus2",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}
Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/westus2/operationStatuses/44444444-4444-4444-4444-444444444444?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/cross-region-restored-cluster",
  "name": "cross-region-restored-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "westus2",
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "PointInTimeRestore",
    "creationSourceClusterResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/source-cluster",
    "creationSourceClusterLocation": "eastus2",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}

Restore a HorizonDB cluster to a point in time

Sample request

PUT https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/restored-cluster?api-version=2026-10-01-preview

{
  "location": "eastus2",
  "properties": {
    "creationMode": "PointInTimeRestore",
    "pointInTimeUtc": "2026-07-27T12:00:00Z",
    "creationSourceClusterResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/source-cluster",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    }
  }
}

Sample response

Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/33333333-3333-3333-3333-333333333333?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/restored-cluster",
  "name": "restored-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "PointInTimeRestore",
    "pointInTimeUtc": "2026-07-27T12:00:00Z",
    "creationSourceClusterResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/source-cluster",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}
Azure-AsyncOperation: https://management.azure.com/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/providers/Microsoft.HorizonDb/locations/eastus2/operationStatuses/33333333-3333-3333-3333-333333333333?api-version=2026-10-01-preview
Retry-After: 30
{
  "id": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/restored-cluster",
  "name": "restored-cluster",
  "type": "Microsoft.HorizonDb/clusters",
  "location": "eastus2",
  "properties": {
    "postgreSqlVersion": "17",
    "creationMode": "PointInTimeRestore",
    "pointInTimeUtc": "2026-07-27T12:00:00Z",
    "creationSourceClusterResourceId": "/subscriptions/ffffffff-ffff-ffff-ffff-ffffffffffff/resourceGroups/example-resource-group/providers/Microsoft.HorizonDb/clusters/source-cluster",
    "network": {
      "publicAccess": "Disabled"
    },
    "backup": {
      "geoRedundancy": "Enabled",
      "retentionDays": 14
    },
    "state": "Provisioning",
    "provisioningState": "Provisioning",
    "readWritePool": {}
  }
}

Definitions

Name Description
AiModelManagementStatus

The AI Model Management status for a HorizonDB cluster.

BackupProperties

Backup configuration properties for a HorizonDB cluster.

Cluster

Represents the HorizonDB cluster.

ClusterCreateMode

Controls how a HorizonDB cluster PUT request is processed.

ClusterProperties

Properties of a HorizonDB cluster.

ClusterState

Current state of a HorizonDB cluster.

createdByType

The type of identity that created the resource.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

ErrorResponse

Error response

GeoRedundancyState

Indicates the geo-redundancy state.

HorizonDbClusterDataEncryption

The Cluster-level data encryption configuration. The encryption type is selected at cluster creation; switching between SystemManaged and AzureKeyVault after creation is not supported. For AzureKeyVault encryption, primaryKeyUri and primaryUserAssignedIdentityId are required, and backup.geoRedundancy must be Disabled. Both primaryKeyUri and primaryUserAssignedIdentityId can be provided during initial cluster creation. For updates to an existing cluster through PUT or PATCH, only one of these properties can change per request, and that update must complete before submitting a separate update to change the other property. Customer-managed key identities must also be assigned to the Cluster through its top-level identity property. Only versionless Azure Key Vault key URIs are supported; key version paths are rejected. For SystemManaged encryption, key and identity properties must be omitted.

HorizonDbClusterDataEncryptionType

The type of data encryption used by a HorizonDB cluster. The type is selected at cluster creation; switching between SystemManaged and AzureKeyVault after creation is not supported.

HorizonDbClusterEncryptionKeyStatus

The validation status of a customer-managed encryption key used by a HorizonDB cluster.

HorizonDbClusterIdentityType

The managed identity types supported by a HorizonDB cluster.

HorizonDbClusterManagedServiceIdentity

The user-assigned managed identities assigned to a HorizonDB cluster. Omitting the entire top-level identity property from PUT or PATCH preserves all current assignments. When userAssignedIdentities is supplied, PUT replaces the complete set and PATCH merges the supplied entries with the existing set; a null PATCH entry removes that individual identity. Setting type to None clears all assignments. Removing an identity referenced by a change data capture identity assignment is rejected until the referencing assignment is deleted.

Network

Network properties.

PostgreSqlVersion

A PostgreSQL major version supported by HorizonDB. API version 2026-10-01-preview accepts 17 and 18. Future API versions may add named values, and clients must tolerate unknown values returned by the service.

ProvisioningState

The provisioning state.

PublicNetworkAccessState

Indicates if public network access is enabled or not.

ReadWritePoolProperties

The pool currently designated to host a HorizonDB cluster's read-write node. When a pool is created while the cluster currently has no pools, the service automatically designates the new pool as the read-write pool. This behavior also applies after all pools that existed earlier in the cluster's lifetime have been deleted.

systemData

Metadata pertaining to creation and last modification of the resource.

UserAssignedIdentity

User assigned identity properties

AiModelManagementStatus

The AI Model Management status for a HorizonDB cluster.

Value Description
Enabled

AI Model Management is enabled.

Disabled

AI Model Management is disabled.

BackupProperties

Backup configuration properties for a HorizonDB cluster.

Name Type Default value Description
earliestRestorePointUtc

string (date-time)

The earliest point in time, in UTC, to which the cluster can currently be restored.

geoRedundancy

GeoRedundancyState

The geo-redundancy state. When creationMode is PointInTimeRestore, the service ignores the requested value during cluster creation and configures the new cluster with the same geo-redundancy setting as the source cluster, for both same-location and cross-location restores. The response reports the inherited setting. Geo-redundant backup is not supported when dataEncryption.type is AzureKeyVault.

retentionDays

integer (int32)

minimum: 1
maximum: 35
7

The number of days that automatic backups are retained. The service defaults to 7 days when this property is omitted.

Cluster

Represents the HorizonDB cluster.

Name Type Description
id

string (arm-id)

Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"

identity

HorizonDbClusterManagedServiceIdentity

The managed service identities assigned to this resource. Omitting the entire identity property from PUT or PATCH preserves all current assignments. When provided, PUT replaces the user-assigned identity set and PATCH merges it; null PATCH dictionary entries remove individual identities. Setting type to None clears all assignments.

location

string

The geo-location where the resource lives

name

string

The name of the resource

properties

ClusterProperties

The resource-specific properties for this resource.

systemData

systemData

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"

ClusterCreateMode

Controls how a HorizonDB cluster PUT request is processed.

Value Description
Create

Process the request as a normal cluster creation.

PointInTimeRestore

Create the cluster from a point-in-time restore.

ClusterProperties

Properties of a HorizonDB cluster.

Name Type Description
aiModelManagement

AiModelManagementStatus

Specifies whether AI Model Management is enabled for the cluster.

backup

BackupProperties

The backup configuration for the cluster.

creationMode

ClusterCreateMode

The mode used to create the cluster. When this property is omitted while creating a new cluster, the service records Create. PointInTimeRestore creates a new cluster from an available backup; pointInTimeUtc and creationSourceClusterResourceId are then required, postgreSqlVersion must be omitted because it is obtained from the backup metadata, and creationSourceClusterLocation is required when the source and target cluster locations differ. During PointInTimeRestore creation, the service ignores the requested backup.geoRedundancy value and configures the new cluster with the same geo-redundancy setting as the source cluster. This property is immutable and is returned as creation provenance. On replacement, omission preserves the recorded value, resubmitting the same value is accepted, and changing it is rejected.

creationSourceClusterLocation

string

The Azure location of the source HorizonDB cluster used for point-in-time restore. This property is optional when the source and target cluster locations are the same. It is required when the source cluster location differs from the target cluster location and must identify the source cluster's location. This property must be absent for creation modes other than PointInTimeRestore or when creationMode is omitted. This immutable creation-provenance value does not change after creation.

creationSourceClusterResourceId

string (arm-id)

The Azure resource ID of the source HorizonDB cluster used by the selected creation mode. This property is required for PointInTimeRestore and other source-based creation modes, and must be absent when creationMode is Create or omitted. A source cluster does not need to have a pool to be restored, provided an available backup exists. This immutable creation-provenance value does not change after creation.

dataEncryption

HorizonDbClusterDataEncryption

The data encryption configuration for the cluster. When omitted during initial cluster creation, the service uses SystemManaged encryption. When supplied during initial cluster creation, type is required. For PUT updates of an existing cluster, type may be omitted; if provided, it must match the existing encryption type. The encryption type is selected at cluster creation; switching between SystemManaged and AzureKeyVault after creation is not supported.

network

Network

The network configuration for the cluster. When this object is omitted, the service defaults it to publicAccess Disabled.

pointInTimeUtc

string (date-time)

The requested point in time, in UTC. This property is required in every PointInTimeRestore request. For a same-location restore, the service restores the latest backup available at or before this value. For a cross-location restore, the service requires but ignores this value and restores the latest available backup; cross-location responses omit this property. This property must be absent for other creation modes or when creationMode is omitted and can only be specified during resource creation.

postgreSqlVersion

PostgreSqlVersion

The PostgreSQL major version used by the HorizonDB cluster. API version 2026-10-01-preview supports versions 17 and 18. For ordinary cluster creation, the version is supplied in the request and is immutable after creation. For point-in-time restore, the service obtains the version from the source backup metadata and the request must omit this property. This API version does not support in-place PostgreSQL major-version upgrades.

provisioningState

ProvisioningState

The provisioning state of the cluster.

readWritePool

ReadWritePoolProperties

The pool currently designated to host the cluster's read-write node.

state

ClusterState

Current state of the cluster.

ClusterState

Current state of a HorizonDB cluster.

Value Description
Ready

Is ready and operational

Provisioning

Is provisioning

Deleting

Is being deleted

Inaccessible

Is inaccessible

Updating

Is being updated

createdByType

The type of identity that created the resource.

Value Description
User
Application
ManagedIdentity
Key

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

object

The additional info.

type

string

The additional info type.

ErrorDetail

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

The error details.

message

string

The error message.

target

string

The error target.

ErrorResponse

Error response

Name Type Description
error

ErrorDetail

The error object.

GeoRedundancyState

Indicates the geo-redundancy state.

Value Description
Enabled

Geo-redundancy is enabled. This value is not supported when dataEncryption.type is AzureKeyVault.

Disabled

Geo-redundancy is disabled

HorizonDbClusterDataEncryption

The Cluster-level data encryption configuration. The encryption type is selected at cluster creation; switching between SystemManaged and AzureKeyVault after creation is not supported. For AzureKeyVault encryption, primaryKeyUri and primaryUserAssignedIdentityId are required, and backup.geoRedundancy must be Disabled. Both primaryKeyUri and primaryUserAssignedIdentityId can be provided during initial cluster creation. For updates to an existing cluster through PUT or PATCH, only one of these properties can change per request, and that update must complete before submitting a separate update to change the other property. Customer-managed key identities must also be assigned to the Cluster through its top-level identity property. Only versionless Azure Key Vault key URIs are supported; key version paths are rejected. For SystemManaged encryption, key and identity properties must be omitted.

Name Type Description
primaryEncryptionKeyCurrentVersion

string

The current version of the primary encryption key used by the cluster. This property is returned for AzureKeyVault encryption and is absent for SystemManaged encryption.

primaryEncryptionKeyStatus

HorizonDbClusterEncryptionKeyStatus

The validation status of the primary encryption key. This property is returned for AzureKeyVault encryption and is absent for SystemManaged encryption.

primaryKeyUri

string (uri)

pattern: ^https://[A-Za-z0-9-]+[.]vault([.]azure[.]net|[.]usgovcloudapi[.]net|[.]azure[.]cn)/keys/[A-Za-z0-9-]+/?$

The versionless Azure Key Vault key URI used to encrypt the cluster's primary storage. Key version paths are not supported. During initial cluster creation, this property can be provided together with primaryUserAssignedIdentityId. For updates to an existing cluster through PUT or PATCH, this property and primaryUserAssignedIdentityId cannot both change in the same request; the first update must complete before submitting a separate update for the other property.

primaryUserAssignedIdentityId

string (arm-id)

The Azure resource ID of the user-assigned managed identity used to access the primary encryption key. The identity must also be assigned to the Cluster through its top-level identity property. During initial cluster creation, this property can be provided together with primaryKeyUri. For updates to an existing cluster through PUT or PATCH, this property and primaryKeyUri cannot both change in the same request; the first update must complete before submitting a separate update for the other property.

type

HorizonDbClusterDataEncryptionType

The type of data encryption used by the cluster. When the data encryption configuration is supplied during initial cluster creation, this property is required. For PUT updates of an existing cluster, this property may be omitted; if provided, it must match the existing encryption type. This value is selected at cluster creation and cannot later be changed from SystemManaged to AzureKeyVault or from AzureKeyVault to SystemManaged.

HorizonDbClusterDataEncryptionType

The type of data encryption used by a HorizonDB cluster. The type is selected at cluster creation; switching between SystemManaged and AzureKeyVault after creation is not supported.

Value Description
SystemManaged

Data encryption is managed by Azure using platform-managed keys.

AzureKeyVault

Data encryption uses customer-managed keys stored in Azure Key Vault.

HorizonDbClusterEncryptionKeyStatus

The validation status of a customer-managed encryption key used by a HorizonDB cluster.

Value Description
Valid

The encryption key is valid and accessible to the configured user-assigned managed identity.

Invalid

The encryption key is invalid or inaccessible to the configured user-assigned managed identity.

HorizonDbClusterIdentityType

The managed identity types supported by a HorizonDB cluster.

Value Description
None

No managed identity is assigned. Setting type to None clears all managed identity assignments.

UserAssigned

User-assigned managed identities are assigned.

HorizonDbClusterManagedServiceIdentity

The user-assigned managed identities assigned to a HorizonDB cluster. Omitting the entire top-level identity property from PUT or PATCH preserves all current assignments. When userAssignedIdentities is supplied, PUT replaces the complete set and PATCH merges the supplied entries with the existing set; a null PATCH entry removes that individual identity. Setting type to None clears all assignments. Removing an identity referenced by a change data capture identity assignment is rejected until the referencing assignment is deleted.

Name Type Description
type

HorizonDbClusterIdentityType

The managed identity type assigned to the cluster. Setting this property to None clears all managed identity assignments.

userAssignedIdentities

<string,  UserAssignedIdentity>

The user-assigned managed identities associated with the cluster. When supplied on PUT, this dictionary replaces the complete set of assignments. When supplied on PATCH, entries are merged with the existing set and a null value removes the corresponding identity. Each dictionary key must be the full Azure resource ID of a Microsoft.ManagedIdentity/userAssignedIdentities resource. Non-null request values can be empty objects; response values contain the service-populated clientId and principalId. Assigning an identity does not grant it access to destination resources; required role assignments must be configured separately.

Network

Network properties.

Name Type Default value Description
publicAccess

PublicNetworkAccessState

Disabled

Specifies whether public access is enabled for the cluster. The service defaults to Disabled when this property is omitted.

PostgreSqlVersion

A PostgreSQL major version supported by HorizonDB. API version 2026-10-01-preview accepts 17 and 18. Future API versions may add named values, and clients must tolerate unknown values returned by the service.

Value Description
17

PostgreSQL major version 17.

18

PostgreSQL major version 18.

ProvisioningState

The provisioning state.

Value Description
Succeeded

Resource has been created.

Failed

Resource creation failed.

Canceled

Resource creation was canceled.

InProgress

The HorizonDB resource operation is actively running.

Provisioning

The HorizonDB resource is still provisioning.

Updating

The resource is being updated.

PublicNetworkAccessState

Indicates if public network access is enabled or not.

Value Description
Enabled

Public network access is enabled

Disabled

Public network access is disabled

ReadWritePoolProperties

The pool currently designated to host a HorizonDB cluster's read-write node. When a pool is created while the cluster currently has no pools, the service automatically designates the new pool as the read-write pool. This behavior also applies after all pools that existed earlier in the cluster's lifetime have been deleted.

Name Type Description
designatedPoolResourceId

string (arm-id)

The Azure resource ID of the pool designated to host the cluster's read-write node. The pool is a child resource of this cluster. When a pool is created while the cluster currently has no pools, the service automatically sets this property to the new pool's resource ID, including when all pools that existed earlier in the cluster's lifetime were deleted. This property is absent when no pool is designated, such as after clearReadWritePool succeeds.

systemData

Metadata pertaining to creation and last modification of the resource.

Name Type Description
createdAt

string (date-time)

The timestamp of resource creation (UTC).

createdBy

string

The identity that created the resource.

createdByType

createdByType

The type of identity that created the resource.

lastModifiedAt

string (date-time)

The timestamp of resource last modification (UTC)

lastModifiedBy

string

The identity that last modified the resource.

lastModifiedByType

createdByType

The type of identity that last modified the resource.

UserAssignedIdentity

User assigned identity properties

Name Type Description
clientId

string (uuid)

The client ID of the assigned identity.

principalId

string (uuid)

The principal ID of the assigned identity.