Migrate from PostgreSQL v1 to v2

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.

Automatic migration

IONOS CLOUD automatically migrates all DBaaS PostgreSQL v1 clusters to the v2 infrastructure. Migrations start on July 29, 2026 and complete within four weeks.

What to expect

• 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.

Required action

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.

Manual migration

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.

1

Phase 1: Target cluster provisioning

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.

1

Provision a v2 cluster

To create a v2 cluster, see Deploy a PostgreSQL Cluster.

2

Run the data transfer script

Run the data transfer script to migrate data from v1 to the newly provisioned v2 cluster.

2

Phase 2: Schema preparation and script architecture

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.

1

Replicate databases, roles, and users

Set up all databases and roles (users and groups) on the new v2 cluster using the exact same names as on v1.

2

Extract data from v1

Use pg_dump to create a consistent export of your v1 cluster:

pg_dump -h <v1-endpoint> -U <username> -d <dbname> -f v1_dump.dump

For 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.dump

3

Import to v2

Pipe the SQL dump file directly into the v2 cluster. The -v ON_ERROR_STOP=1 flag stops the script immediately on any error, preventing silent failures:

psql -h <v2-endpoint> -U <username> -d <dbname> -v ON_ERROR_STOP=1 -f v1_dump.dump

3

Phase 3: Migration execution

Schedule 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.

1

Stop application writes to v1

Place your application into maintenance mode or revoke write permissions on the v1 cluster to keep the data static.

2

Verify log completion

Confirm that pg_dump has fully written the dump file by checking its last line:

• Run: tail -n 5 v1_dump.dump
• Confirm the presence of: -- PostgreSQL database dump complete

3

Monitor exit code

The ON_ERROR_STOP=1 flag stops psql immediately if any command fails. Check the shell exit code right after the process finishes:

• Run: echo $?
• 0 means success. Any other value means the process stopped due to a SQL error or connection drop.

4

Validate data integrity

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.

5

Update monitoring and observability

PostgreSQL v2 removes the explicit /logs API endpoint. Enable logsEnabled and metricsEnabled on your v2 cluster to route telemetry to the IONOS CLOUD Logging and Monitoring platform.

6

Redirect traffic and go live

Update your application's connection configuration with the new v2 primaryInstanceAddress and bring the application back online.