# PostgreSQL API Versions

DBaaS PostgreSQL offers [<mark style="color:blue;">PostgreSQL v2</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v2-api) and [<mark style="color:blue;">PostgreSQL v1</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v1-api) APIs. **PostgreSQL v2** is the recommended version—it supports multi-region deployments, idempotent cluster management via the Ensure pattern, dedicated backup location management, and improved privilege separation compared to v1.

{% hint style="warning" %}
**Important:** The **PostgreSQL v1** API will be deprecated in an upcoming release. All existing clusters operating on the v1 version will be automatically migrated to the v2 version as part of this process. No user action is required. For more information, see [<mark style="color:blue;">Version comparison</mark>](#version-comparison).
{% endhint %}

## Which PostgreSQL API version should I use?

{% hint style="info" %}
**Note:** **PostgreSQL v1** and **PostgreSQL v2** refer to IONOS Cloud's DBaaS API versions, not PostgreSQL software versions.
{% endhint %}

Use **PostgreSQL v2** if you are:

* Starting a new PostgreSQL deployment on IONOS Cloud.
* Requiring multi-region cluster management via region-specific endpoints.
* Need idempotent cluster provisioning and updates using the Ensure (`PUT`) pattern.
* Requiring dedicated backup location management for geographic data safety.

Use **PostgreSQL v1** only if you have existing integrations that depend on v1 endpoints.

## Version comparison

The section highlights the key differences between PostgreSQL v1 and v2 APIs, including the changes and the impact of v2.

<details>

<summary><strong>General API Architecture and Infrastructure</strong></summary>

This section covers changes to the base endpoints, regionality, and high-level API structure.

| **Feature**                  | **PostgreSQL v1 (1.0.0)**                                                             | **PostgreSQL v2 (2.0.0)**                                                                                                                                                                                                 | **Impact in v2**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Server model**             | Single global base URL `https://api.ionos.com/databases/postgresql`                   | [<mark style="color:blue;">Region-specific endpoints</mark>](https://docs.ionos.com/cloud/databases/postgresql/v2-api#endpoints) for Berlin, Frankfurt, Paris, Logroño, London, Worcester, Las Vegas, Lenexa, and Newark. | Reduces network latency for management operations and improves potential performance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Resource grouping (Tags)** | Available tags are Clusters, Backups, Restores, Logs, Users, Databases, and Metadata. | Available tags are Clusters, Backups, Backup Locations, and Versions.                                                                                                                                                     | <p>Introduces tag renames and conceptual shifts.</p><ul><li>Replaces <strong>Metadata</strong> with <strong>Versions</strong>, which offers a clearer separation for supported version listings.</li><li>New explicit tags, such as <code>BackupLocations</code>, were added to enhance the safety of geographic data.</li><li>Dedicated restore tags are removed in favor of a declarative <code>restoreFromBackup</code> property used directly within the <code>Clusters</code> tag when creating or ensuring a cluster.</li><li>The explicit <code>Logs</code> tag was removed, indicating a shift toward other operational observability methods.</li><li>Retrieving snapshot locations is possible.</li></ul> |

</details>

<details>

<summary><strong>Cluster Management and Networking</strong></summary>

This section details changes to the cluster object properties, lifecycle states, and network connections.

| **Feature**             | **PostgreSQL v1 (1.0.0)**                                                                                                               | **PostgreSQL v2 (2.0.0)**                                                                                                    | **Change or Impact in v2**                                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Cluster object**      | Supports basic lifecycle states, such as `BUSY`, `AVAILABLE`, and `DESTROYING`.                                                         | Supports granular lifecycle states such as `PROVISIONING`, `PROVISIONED`, `DESTROYING`, `FAILED`, `connection`, and `state`. | More granular operational and infrastructure metadata.                                                                     |
| **Compute and Storage** | Instance and storage specifications are defined as top-level properties: `instances`, `cores`, `ram`, `storageSize`, and `storageType`. | Group these details into a single instance object containing `count`, `ram`, `cores`, and `storageSize`.                     | Reduces clutter at the top level of the cluster properties and makes the payload easier for developers to read and manage. |
| **Network connection**  | Uses a connections array, allowing multiple connection objects containing `datacenterId`, `lanId`, and `cidr`.                          | Uses a single connection object containing `datacenterId`, `lanId`, and replaces cidr with `primaryInstanceAddress`.         | Enforces a predictable network model.                                                                                      |

</details>

<details>

<summary><strong>Replication and Connection Pooling</strong></summary>

This section details changes to the replication and connection pooling.

| **Feature**           | **PostgreSQL v1 (1.0.0)**                                                                                               | **PostgreSQL v2 (2.0.0)**                                                               | **Change or Impact in v2**                                                                          |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Replication**       | Uses `synchronizationMode`. `ASYNCHRONOUS` and `STRICTLY_ASYNCHRONOUS` are supported. `SYNCHRONOUS` mode is deprecated. | Renamed to `replicationMode`. `ASYNCHRONOUS` and `STRICTLY_ASYNCHRONOUS` are supported. | Clarified terminology in alignment with native database terminology.                                |
| **Connection Pooler** | Modeled as an object: {"enabled": true, "poolMode": "transaction"}.                                                     | Modeled as a direct string value: "TRANSACTION".                                        | Reduces clutter in the cluster configuration payload. You can define the required pooling directly. |

</details>

<details>

<summary><strong>Identity and Authentication</strong></summary>

This section details changes to the credential object and authorization method.

| **Feature**       | **PostgreSQL v1 (1.0.0)**                                                                                    | **PostgreSQL v2 (2.0.0)**                                              | **Change or Impact in v2**                                                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Credentials**   | Accepts `username` and `password`. Databases are created separately using a dedicated `/databases` endpoint. | Accepts `username`, `password`, and explicitly adds the database name. | Abstracts database management and removes explicit database creation endpoints. Database creation is folded directly into the cluster's main configuration. |
| **Authorization** | The `basicAuth` and `tokenAuth` are supported.                                                               | Supports only the `tokenAuth` method.                                  | Benefits the user primarily by contributing to a streamlined, stronger security model.                                                                      |

</details>

<details>

<summary><strong>Backup and Restore</strong></summary>

This section details changes to the backup and restore operations.

| **Feature** | **PostgreSQL v1 (1.0.0)**                                                         | **PostgreSQL v2 (2.0.0)**                                                                | **Change or Impact in v2**                                                            |
| ----------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Backups** | Uses the `fromBackup` object, which contains `backupId` and `recoveryTargetTime`. | Renamed to `restoreFromBackup` containing `sourceBackupId` and `recoveryTargetDatetime`. | Explicitly identifies that the specified backup is the source for the cluster's data. |

</details>

<details>

<summary><strong>Observability</strong></summary>

This section covers logging and metrics.

| **Feature** | **PostgreSQL v1 (1.0.0)**                               | **PostgreSQL v2 (2.0.0)**                                                                                                                     | **Change or Impact in v2**                                                                                                                                                                                      |
| ----------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Logs**    | Handles observability via an explicit `/logs` endpoint. | Removes the explicit logs endpoint and adds `logsEnabled` (boolean) and `metricsEnabled` (boolean) directly to the cluster object properties. | Logs and metrics are now seamlessly forwarded to a dedicated, centralized observability platform, such as the IONOS Cloud Logging and Monitoring Services, rather than being streamed through the database API. |

</details>

## Related topics

After reviewing the PostgreSQL API versions, explore the following topics to get started with PostgreSQL APIs.

* [<mark style="color:blue;">PostgreSQL v2 API</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v2-api): Reference documentation for the recommended v2 API, including region-specific endpoints and available operations.
* [<mark style="color:blue;">PostgreSQL v1 API</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v1-api): Reference documentation for the v1 API, for users with existing integrations before migrating to v2.
* [<mark style="color:blue;">Get Started with PostgreSQL v2 API</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v2-api/workflows/get-started): A guided workflow for deploying and managing your first PostgreSQL cluster using the v2 API.
* [<mark style="color:blue;">View Cluster and Verify Backups</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v2-api/workflows/view-cluster-verify-backup): Inspect an existing cluster, verify its backup location, and confirm backup details.
* [<mark style="color:blue;">Database Migration</mark>](https://docs.ionos.com/cloud/databases/postgresql/api/v1-api/migration): Migrate PostgreSQL data between clusters, including from on-premises or v1-based deployments.