> 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/api/v1-v2-api-versions.md).

# PostgreSQL API Versions

DBaaS PostgreSQL offers [<mark style="color:blue;">PostgreSQL v2</mark>](/cloud/databases/postgresql/api/v2-api.md) and [<mark style="color:blue;">PostgreSQL v1</mark>](/cloud/databases/postgresql/api/v1-api.md) 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:**

* Use [<mark style="color:blue;">PostgreSQL v2 API</mark>](/cloud/databases/postgresql/api/v2-api.md) to create clusters. Creation of clusters using [<mark style="color:blue;">PostgreSQL v1 API</mark>](/cloud/databases/postgresql/api/v1-api.md) will be deprecated soon.
* Existing v1 clusters will be automatically migrated to v2 and no user action is required. We will notify you before the migration.
  {% endhint %}

## 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>](/cloud/databases/postgresql/api/v2-api.md#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, Storage, 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`, `AVAILABLE`, `UPDATING`, `DESTROYING`, and `FAILED`.                                           | 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`. **HDD**, **SSD Standard**, and **SSD Premium** `storageType` are supported. | Group these details into a single instance object containing `count`, `ram`, `cores`, and `storageSize`. Only **SSD Premium** `storageType` is supported. | Reduces clutter at the top level of the cluster properties and makes the payload easier for developers to read and manage. For optimal IOPS performance, **SSD Premium** is offered. |
| **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.                                                                                                                                                |
| **Supported PostgreSQL versions** | Versions 14, 15, and 16.                                                                                                                                                                                            | Versions 14, 15, 16, 17, and 18.                                                                                                                          | v2 adds support for PostgreSQL 17 and 18, enabling access to the latest features and long-term support releases.                                                                     |

</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 <code class="expression">space.vars.ionos\_cloud</code> 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>](/cloud/databases/postgresql/api/v2-api.md): Reference documentation for the recommended v2 API, including region-specific endpoints and available operations.
* [<mark style="color:blue;">PostgreSQL v1 API</mark>](/cloud/databases/postgresql/api/v1-api.md): 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>](/cloud/databases/postgresql/api/v2-api/workflows/get-started.md): 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>](/cloud/databases/postgresql/api/v2-api/workflows/view-cluster-verify-backup.md): Inspect an existing cluster, verify its backup location, and confirm backup details.
* [<mark style="color:blue;">Database Migration</mark>](/cloud/databases/postgresql/api/v1-api/migration.md): Migrate PostgreSQL data between clusters, including from on-premises or v1-based deployments.


---

# 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/api/v1-v2-api-versions.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.