HorizonDB preview: automate a reproducible lab with ARM

Azure HorizonDB is a new database service on Azure. It is PostgreSQL-compatible from a developer perspective, but its storage layer differs to support built-in high availability and scalability.

Since it's currently in preview, APIs might evolve and defaults could change. This is a great opportunity to explore how well PostgreSQL works with your existing applications.

If you're setting up a lab for those tests, you don’t want to navigate the UI each time. You need something that can be recreated quickly and dismantled once finished.

Azure Resource Manager (ARM) is well suited for that.

Login to Azure

I installed the Azure CLI and logged in on my laptop:


az login

This opens the browser, lets me sign in interactively, and lets me select the tenant and subscription.

If I'm already logged in, I can get my subscription ID:


az account show --query id -o tsv

From there, everything can be automated via the CLI.

ARM template for HorizonDB preview

I created a parameterized template, in hdb-template.json:


{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "apiVersion":         { "type": "string", "defaultValue": "2026-01-20-preview" },
        "clusterName":        { "type": "string" },
        "location":           { "type": "string" },
        "poolName":           { "defaultValue": "DefaultPool", "type": "string" },
        "administratorLogin": { "type": "string" },
        "administratorLoginPassword": { "type": "securestring" },
        "tags":               { "type": "object", "defaultValue": {} },
        "firewallRules":      { "type": "array", "defaultValue": [] },
        "guid":               { "type": "string", "defaultValue": "[newGuid()]" }
    },
    "resources": [
        {
            "type": "Microsoft.HorizonDB/clusters",
            "apiVersion": "[parameters('apiVersion')]",
            "name": "[parameters('clusterName')]",
            "location": "[parameters('location')]",
            "properties": {
                "createMode":                 "Default",
                "version":                    "17",
                "zonePlacementPolicy":        "BestEffort",
                "replicaCount":               2,
                "vCores":                     2,
                "administratorLogin":         "[parameters('administratorLogin')]",
                "administratorLoginPassword": "[parameters('administratorLoginPassword')]",
                "network":                    { "publicNetworkAccess": "Enabled" },
                "aiModelManagement":          1
            },
            "tags":                           "[parameters('tags')]"
        },
        {
            "condition": "[greater(length(parameters('firewallRules')), 0)]",
            "type": "Microsoft.Resources/deployments",
            "apiVersion": "2019-08-01",
            "name": "[concat('firewallRules-', parameters('guid'), '-', copyIndex())]",
            "copy": {
                "count": "[if(greater(length(parameters('firewallRules')), 0), length(parameters('firewallRules')), 1)]",
                "mode": "Serial",
                "name": "firewallRulesIterator"
            },
            "dependsOn": [
                "[concat('Microsoft.HorizonDB/clusters/', parameters('clusterName'))]"
            ],
            "properties": {
                "mode": "Incremental",
                "template": {
                    "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
                    "contentVersion": "1.0.0.0",
                    "resources": [
                        {
                            "type": "Microsoft.HorizonDB/clusters/pools/firewallRules",
                            "name": "[concat(parameters('clusterName'),'/',parameters('poolName'),'/',parameters('firewallRules')[copyIndex()].name)]",
                            "apiVersion": "[parameters('apiVersion')]",
                            "properties": {
                                "Description": "[parameters('firewallRules')[copyIndex()].name]",
                                "StartIpAddress": "[parameters('firewallRules')[copyIndex()].startIpAddress]",
                                "EndIpAddress": "[parameters('firewallRules')[copyIndex()].endIpAddress]"
                            }
                        }
                    ]
                }
            }
        }
    ]
}

This template defines the HorizonDB cluster and its configuration. I generated it the first time I manually created a cluster via the UI portal. I include the firewall rules in a loop to define multiple client IPs.

Keeping firewall rules in the template makes the lab fully reproducible, including network access, without requiring additional CLI commands.

HorizonDB parameters

In hdb-parameters.json I put all my parameters used by the ARM templates:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "clusterName":                { "value": "franckpachot-hdb" },
    "location":                   { "value": "swedencentral" },
    "administratorLogin":         { "value": "franck" },
    "tags":          { "value":   { "Owner": "franckpachot" } },
    "firewallRules": {
      "value": [
        { "name": "home",  "startIpAddress": "192.0.2.10",    "endIpAddress": "192.0.2.20" },
        { "name": "shell", "startIpAddress": "52.178.13.135", "endIpAddress": "52.178.13.135" }
      ]
    }
  }
}

This file contains all environment-specific values: cluster name, region, allowed IP ranges, and admin user. You must update them. The regions where HorizonDB preview is available are listed here: https://learn.microsoft.com/en-us/azure/horizondb/overview#azure-regions

I do not store the password in the parameters file and pass it at deployment time.

Resource group

I create a resource group that will contain everything:


az group create --name franckpachot-rg --location swedencentral

This makes it easy to identify and delete everything related to the lab.

You will change the location to the region you chose above, and the resource group name will be used in the next command.

Deploy the cluster

A single command deploys the cluster from the template:


az deployment group create --resource-group franckpachot-rg --template-file hdb-template.json --parameters @hdb-parameters.json --parameters administratorLoginPassword=PostgreSQL@Azure

The template defines the infrastructure. The parameters define the environment, and the CLI command combines both.

The deployment takes about 15 minutes.

Retrieve the endpoint and connect

The endpoint is visible in the Azure portal, but it can also be retrieved directly from the CLI:


az resource show --resource-type Microsoft.HorizonDB/clusters --name franckpachot-hdb --resource-group franckpachot-rg --query properties.fullyQualifiedDomainName -o tsv

I set my PostgreSQL connection variables using the credentials used when creating it, and the hostname of the endpoint:

export PGPORT=5432
export PGUSER=franck
export PGPASSWORD=PostgreSQL@Azure
export PGDATABASE=postgres
export PGHOST=

You can then connect with psql or any PostgreSQL client, including the PostgreSQL extension for Visual Studio Code

Let's check the version banner and a few parameters:


$ psql
psql (16.2, server 17.9 (Azure HorizonDB (70f3b593ec7)(release)))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=> select version();

                                                        version
-----------------------------------------------------------------------------------------------------------------------
 PostgreSQL 17.9 (Azure HorizonDB (70f3b593ec7)(release)) on x86_64-pc-linux-gnu, compiled by gcc (GCC) 13.2.0, 64-bit

(1 row)

postgres=> \dconfig azure*

                List of configuration parameters

                 Parameter                  |       Value
--------------------------------------------+-------------------
 azure.accepted_password_auth_method        | md5,scram-sha-256
 azure.enable_temp_tablespaces_on_local_ssd | on
 azure.extensions                           |
 azure.fabric_mirror_enabled                | off
 azure.service_principal_id                 |
 azure.service_principal_tenant_id          |
(6 rows)

postgres=> \dconfig shared*

                                        List of configuration parameters

            Parameter             |                                    Value
----------------------------------+------------------------------------------------------------------------------
 shared_buffers                   | 11241MB
 shared_memory_size               | 11776MB
 shared_memory_size_in_huge_pages | 5888
 shared_memory_type               | mmap
 shared_preload_libraries         | azure, orion_storage, pg_availability, pg_qs, pgms_stats, pgms_wait_sampling

(5 rows)

postgres=> show effective_cache_size;
 effective_cache_size
----------------------
 11241MB
(1 row)

postgres=> show full_page_writes;
 full_page_writes
------------------
 off
(1 row)

An interesting aspect is the memory setup. On a 2 vCore, 16 GiB RAM instance, shared_buffers is allocated about 11 GB, which exceeds typical PostgreSQL recommendations.

Traditionally, PostgreSQL utilizes both its buffer cache and the OS filesystem cache. In HorizonDB with disaggregated storage, the PostgreSQL fork avoids double buffering, and shared_buffers and effective_cache_size are closely aligned.

Additionally, full_page_writes is turned off. This is uncommon in PostgreSQL, but justified here because the storage layer already ensures data consistency without torn pages, and has a huge impact on performance.

To use extensions, create a parameter group and set azure.extensions. Managed services must control PostgreSQL extensibility because extensions can gain elevated system privileges.

Cleanup

The advantage of the resource group is that you can delete everything with a single command:


az group delete --name franckpachot-rg --yes

This removes the cluster and all associated resources.

Final thoughts

HorizonDB is currently in preview, and this is a perfect chance to test it!

With ARM and Azure CLI:

You can set up a lab in just 15 minutes
Test how PostgreSQL applications work with it
Explore various extensions and features
And easily clean everything up when you're done

This way, you can focus on what really matters: understanding how this PostgreSQL‑compatible platform performs with your applications and workloads. Please share your comments and feedback.