Migrate from PostgreSQL v1 to v2
Last updated
Was this helpful?
PostgreSQL v2 is in General Availability (GA), offering region-specific endpoints, a redesigned cluster resource model, and a structured cluster lifecycle. IONOS CLOUD automatically migrates all v1 clusters to v2. For more information, see Automatic migration. If you prefer to migrate proactively before the automatic window, see Manual migration.
Important: This guide covers migrating from the PostgreSQL v1 API to the v2 API, a change in IONOS CLOUD's DBaaS API version, not an upgrade of your supported PostgreSQL version. For engine version upgrades, see Upgrade and Maintenance.
IONOS CLOUD automatically migrates all DBaaS PostgreSQL v1 clusters to the v2 infrastructure. Migrations start on July 29, 2026 and complete within four weeks.
Temporary downtime: Your cluster is unavailable during the migration. Downtime is typically between a few seconds and a few minutes.
Schedule: Migrations run Monday through Thursday. IONOS CLOUD notifies you of the exact migration time before migrating your cluster.
No endpoint change: Your cluster connection endpoint stays the same. Applications reconnect automatically once the migration completes.
Important: Action required for API, SDK, or IaC users: PostgreSQL v2 does not support basic authentication for cluster management. You must use authentication token for API and SDKs. For more information, see Generate authentication token.
If you do not manage your clusters programmatically, or already use token authentication, no further action is needed.
To migrate your cluster before the automatic window, follow the steps in this guide. The process covers provisioning a target v2 cluster, transferring data using pg_dump and psql, and executing a controlled cutover of your application.
Prerequisites: Before provisioning, review the following architectural changes introduced in PostgreSQL v2:
Migrate API endpoints: PostgreSQL v2 no longer supports the legacy v1 global endpoint. Use the new, region-specific Endpoints for provisioning and cluster management.
Immediate database declaration: In PostgreSQL v2, specify the target database name in the initial provisioning payload.
Capture connection metadata: Record the newly generated primaryInstanceAddress and associated credentials, and update your script configuration to point to the new v2 host.
To create a v2 cluster, see Deploy a PostgreSQL Cluster.
Prerequisite: The target v2 cluster must have all databases, users, and groups from the source v1 system, with identical database-level permissions.
Warning: A standard database dump includes object permissions (GRANT statements) but not user definitions. If you skip this step, the psql import fails when it applies permissions to users that do not exist on the target cluster.
Recommendation: Use the native pg_dump to export database structure and data. It automatically handles sequences, views, extensions, and object dependencies.
Use pg_dump to create a consistent export of your v1 cluster:
pg_dump -h <v1-endpoint> -U <username> -d <dbname> -f v1_dump.dumpFor a performance-optimized restore, dump the table structure and data separately and disable triggers (this also deactivates foreign key checks during import):
# Database structure
pg_dump -h <v1-endpoint> -U <username> -d <dbname> -s -f v1_schema_dump.dump
# Database contents
pg_dump -h <v1-endpoint> -U <username> -d <dbname> -a --disable-triggers -f v1_data_dump.dumpSchedule a maintenance window for your application to avoid data drift or split-brain scenarios. Do not run the migration during the scheduled maintenance window of either your v1 or v2 cluster.
Compare row counts for your most critical tables to confirm consistency across clusters:
Run SELECT count(*) FROM <table_name>; on both the v1 and v2 databases and compare the results.
For tables with high-frequency updates, compare MAX(id) or the most recent created_at timestamp to confirm the data is current.
Last updated
Was this helpful?
Was this helpful?