> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/databases/postgresql/how-tos/migrate-from-v1-v2.md).

# Migrate from PostgreSQL v1 to v2

PostgreSQL v2 is in [<mark style="color:blue;">General Availability (GA)</mark>](/cloud/release-notes/previous-releases/2026/may-2026.md#dbaas-postgresql-v2-api-in-general-availability), offering region-specific endpoints, a redesigned cluster resource model, and a structured cluster lifecycle. <code class="expression">space.vars.ionos\_cloud</code> automatically migrates all v1 clusters to v2. For more information, see [<mark style="color:blue;">Automatic migration</mark>](#automatic-migration). If you prefer to migrate proactively before the automatic window, see [<mark style="color:blue;">Manual migration</mark>](#manual-migration).

{% hint style="warning" %}
**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 [<mark style="color:blue;">supported PostgreSQL version</mark>](/cloud/databases/postgresql/overview.md#supported-postgresql-versions). For engine version upgrades, see [<mark style="color:blue;">Upgrade and Maintenance</mark>](/cloud/databases/postgresql/overview/upgrade-maintenance.md).
{% endhint %}

## Automatic migration

<code class="expression">space.vars.ionos\_cloud</code> 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. <code class="expression">space.vars.ionos\_cloud</code> 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

{% hint style="warning" %}
**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 [<mark style="color:blue;">Generate authentication token</mark>](/cloud/set-up-ionos-cloud/management/identity-access-management/token-manager.md#generate-authentication-token).
{% endhint %}

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.

{% stepper %}
{% step %}

### Phase 1: Target cluster provisioning

{% hint style="info" %}
**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 [<mark style="color:blue;">Endpoints</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Overview/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.
  {% endhint %}

{% stepper %}
{% step %}

#### Provision a v2 cluster

To create a v2 cluster, see [<mark style="color:blue;">Deploy a PostgreSQL Cluster</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/PostgreSQL-v2-API-Workflows/Deploy-a-PostgreSQL-Cluster).
{% endstep %}

{% step %}

#### Run the data transfer script

Run the data transfer script to migrate data from v1 to the newly provisioned v2 cluster.
{% endstep %}
{% endstepper %}
{% endstep %}

{% step %}

### Phase 2: Schema preparation and script architecture

{% hint style="info" %}
**Prerequisite:** The target v2 cluster must have all databases, users, and groups from the source v1 system, with identical database-level permissions.
{% endhint %}

{% hint style="warning" %}
**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.
{% endhint %}

**Recommendation:** Use the native `pg_dump` to export database structure and data. It automatically handles sequences, views, extensions, and object dependencies.

{% stepper %}
{% step %}

#### 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.
{% endstep %}

{% step %}

#### Extract data from v1

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

```bash
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):

```bash
# 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
```

{% endstep %}

{% step %}

#### 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:

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

{% endstep %}
{% endstepper %}
{% endstep %}

{% step %}

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

{% stepper %}
{% step %}

#### Stop application writes to v1

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

{% step %}

#### 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`
  {% endstep %}

{% step %}

#### 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.
  {% endstep %}

{% step %}

#### 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.
  {% endstep %}

{% step %}

#### 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 <code class="expression">space.vars.ionos\_cloud</code> Logging and Monitoring platform.
{% endstep %}

{% step %}

#### Redirect traffic and go live

Update your application's connection configuration with the new v2 `primaryInstanceAddress` and bring the application back online.
{% endstep %}
{% endstepper %}
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ionos.com/cloud/databases/postgresql/how-tos/migrate-from-v1-v2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.