Migrate PostgreSQL to Azure HorizonDB using Azure Database Migration Service

Azure HorizonDB is a fully managed, PostgreSQL-compatible database service designed for mission-critical and AI-ready workloads. This article describes an offline migration approach based on Azure Database Migration Service (DMS) for moving PostgreSQL workloads to HorizonDB.

The procedure applies to supported PostgreSQL sources, including Azure Database for PostgreSQL flexible server, PostgreSQL on Azure virtual machines, on-premises PostgreSQL, Amazon RDS or Aurora for PostgreSQL, Google Cloud SQL for PostgreSQL, and other PostgreSQL-compatible environments.

Important

Database Migration Service support for PostgreSQL-to-HorizonDB migrations is in preview. Before a production migration, confirm regional availability, supported source versions, networking options, extension compatibility, feature limitations, and operational limits.

Migration workflow

The migration process follows these general stages:

  1. Assess compatibility and select the target HorizonDB cluster configuration.
  2. Prepare source access, networking, credentials, users, roles, and extensions.
  3. Export users and roles and restore them into HorizonDB.
  4. Stop source writes and perform the offline migration.
  5. Validate data, objects, security, and application behavior.
  6. Redirect applications to HorizonDB and monitor.

Plan the migration

Before you begin, ensure the following prerequisites and readiness steps are in place:

  • Provision a HorizonDB cluster in a supported region and select compute appropriate for the initial load and expected production workload.
  • Configure public access or private endpoints, firewall rules, and TLS requirements.

Execute the migration

To execute the migration, create the target, create a DMS resource, export users and roles, configure and start the migration in DMS, and recreate environment-specific configuration.

1. Create and configure the HorizonDB target

  1. Create a HorizonDB cluster in the required subscription, resource group, and region.
  2. If the source uses extensions, confirm that HorizonDB supports them and add the required extensions to the target allow list. Complete any required shared_preload_libraries configuration and restart described in Create extensions before starting the migration.
  3. Configure public or private connectivity and verify name resolution from the migration host.
  4. Temporarily scale compute for the initial load if testing shows that it shortens the maintenance window. Resize to the intended production configuration after validation.

2. Create a Database Migration Service resource

Create the DMS resource that runs the migration.

  1. In the Azure portal, open Azure Database Migration Service and select Create.

  2. For Source server type, select PostgreSQL for any supported source. For Target server type, select Azure HorizonDB. The supported scenarios list on this page doesn't include every supported source, such as Azure Database for PostgreSQL flexible server. You select your specific source server type when you create the migration.

  3. For Database Migration Service, select Database Migration Service, and then select Select.

    Screenshot of the migration scenario page with PostgreSQL as the source server type, Azure HorizonDB as the target server type, and Database Migration Service selected.

  4. On the Basics tab, select your subscription and resource group, select a Location, and enter a Migration service name. When possible, choose the same region as your source and target to minimize network latency.

    Screenshot of the Basics tab with Contoso-subscription, Rg-migration-contoso, West US 2, and DMS-pg-migrate as the migration service name.

  5. Select Review + create, verify the settings, review the terms, and then select Create.

    Screenshot of the Review + create tab with the terms and the Contoso-subscription, Rg-migration-contoso, DMS-pg-migrate, and West US 2 settings.

  6. When the deployment finishes, open the DMS resource.

3. Export users, roles, and permissions

Before starting the data migration, export and restore the roles that own database objects or access the migrated data.

Run the role export from a secure bash-compatible migration host that has the pg_dumpall and psql client utilities installed. Use utilities whose major version is the same as or higher than both the source server and HorizonDB, and check it with psql --version. Store the output securely because role definitions contain security-sensitive metadata.

pg_dumpall --roles-only --no-role-passwords --host=<source-host> --port=5432 --username=<source-admin> --file=roles.sql

The --no-role-passwords option avoids reading password verifiers from pg_authid, which administrators can't access on restricted sources such as Azure Database for PostgreSQL flexible server. For more information, see Dump roles from a flexible server.

Review roles.sql before restoring it. Remove provider-managed roles, unsupported attributes, commands that require superuser privileges, and ownership references that should map to another HorizonDB role.

psql "host=<horizondb-host> port=5432 dbname=postgres user=<target-admin> sslmode=require" --file=roles.sql

Set passwords separately for restored roles that can sign in. Use your approved secret-management process and complete this step before validation and cutover. The export doesn't include passwords.

4. Configure and start the migration

Open the DMS resource and select New migration.

Select PostgreSQL as the Source type, select your Source server type, and select Azure HorizonDB as the Target server type. Select Offline as the Migration mode, review the Migration prerequisites, and then select Continue.

Screenshot of the New migration page with PostgreSQL as the source type, On-premises server as the source server type, Azure HorizonDB as the target server type, and Offline as the migration mode.

On the Source tab, enter the source server details, authentication information, and connection settings.

Configure access from DMS, not just from the host that runs pg_dumpall. DMS manages the migration infrastructure; you don't need to deploy migration virtual machines. Under Connectivity, select the connection method for the source:

  • For IP allowlist - connect using public IPs, use Copy all to copy the displayed Migration service IP addresses. Allow those addresses through the source firewall and any applicable network access rules on the database port, typically 5432. Use the actual addresses displayed in your migration wizard, not the example addresses in the screenshot.
  • For VNet peering - private connection using virtual network, configure the virtual network connection and peering. Verify that routes, private DNS resolution, and network security rules let DMS reach the source hostname and database port.

Select Test connection and resolve any errors before continuing to the target.

Screenshot of the Source tab with the source server fields, port 5432, the IP allow list connectivity method, and example migration service IP addresses.

On the Target tab, select the subscription, resource group, location, and Server name of your HorizonDB cluster, verify the FQDN name, and enter the Admin username and Password. Under Connectivity, select the public IP allow list or private virtual network connection method for the target. For public access, allow the displayed migration service IP addresses through the target firewall. For private access, configure the target network connection and verify routing, private DNS resolution, and database-port access from DMS.

Select Test connection and resolve any errors before continuing.

Screenshot of the Target tab with Contoso-subscription, Rg-migration-contoso, West US 2, the contoso-pg-sales server and FQDN, a masked password, and example migration service IP addresses.

On the Databases tab, select the databases to migrate, and then review the configuration on the Settings and Review tabs. Before starting the migration, stop application writes and pause all scheduled jobs and integrations that modify the source. Keep the source database running so DMS can read it.

Start the migration and monitor it until the data copy completes successfully. Offline migration doesn't synchronize later source changes. Keep all source writers stopped through validation and the switch to HorizonDB.

5. Recreate environment-specific configuration

  • Apply role memberships, grants, default privileges, and schema ownership.
  • Configure application parameters and connection pooling based on HorizonDB guidance.
  • Recreate monitoring, alerts, diagnostic settings, and operational runbooks.
  • Update scheduled jobs and external integrations to use HorizonDB, but keep them paused until validation and cutover are complete.
  • Recreate endpoints, firewall rules, private DNS links, and client certificates as applicable.

Validate and cut over

Complete validation before redirecting production traffic. Record evidence for each acceptance criterion and obtain application-owner approval.

Validation area Minimum acceptance criteria
Database objects Expected schemas, tables, indexes, views, sequences, functions, triggers, and extensions are present.
Data integrity Row counts and application-specific aggregates match, with approved explanations for any differences.
Security Roles, memberships, grants, ownership, and application identities function as designed.
Application Smoke tests, integrations, background jobs, and critical transactions complete successfully.
Operations Monitoring, alerts, backup expectations, runbooks, and escalation paths are ready.

Cut over to HorizonDB

  1. Confirm that the offline migration completed successfully and that all validation criteria are met.
  2. Notify stakeholders and obtain application-owner approval to switch to HorizonDB. Keep source writers stopped.
  3. Update application secrets, connection strings, DNS aliases, or configuration to use the HorizonDB endpoint.
  4. Start applications and resume scheduled jobs and integrations against HorizonDB. Monitor errors, latency, connection counts, and resource consumption.

Troubleshooting

Issue Likely cause Resolution
Connection timeout or name-resolution failure Firewall, private endpoint, route, or DNS configuration For DMS failures, verify the migration service IP allow list or private network configuration, DNS, routes, and database-port access, then rerun Test connection for the affected endpoint. For pg_dumpall or psql failures, validate connectivity from the host running that command.
Permission denied during dump Source account can't read all schemas or large objects Grant the minimum required source permissions or use an approved migration role.
Role or ownership errors during restore Managed-service roles or unsupported attributes in the role script Remove provider-managed roles and unsupported attributes from roles.sql, map ownership to target roles, and apply grants after the data migration. Use --no-role-passwords when exporting from restricted sources and set role passwords separately.
Extension doesn't exist Extension isn't allowed, installed, or available Allow and create the supported extension, select an alternative, or remove the dependency in the source.
Migration is slower than expected Undersized target compute, network latency between DMS and the databases, or index build time Create DMS in the same region as the source and target when possible, and temporarily scale HorizonDB compute for the initial load.
Application fails after cutover Connection string, TLS, permissions, parameters, or extension behavior differs Check client logs and target logs, retest authentication and TLS, and compare the compatibility inventory.