The IONOS CLOUD DBaaS PostgreSQL v2 API provides managed PostgreSQL clusters on region-specific endpoints. It introduces an idempotent Ensure pattern for cluster updates, dedicated backup location management, token-only authentication, granular cluster lifecycle states, a declarative restore model, and direct integration with IONOS CLOUD Logging and Monitoring Services compared to the v1 API. If you are new to the PostgreSQL v2 API, see What Can You Do with the PostgreSQL v2 API?. If you are migrating from v1, see DBaaS PostgreSQL API Versions.

The IONOS CLOUD DBaaS PostgreSQL v2 API provides a consistent interface to manage the complete lifecycle of your highly available PostgreSQL clusters. Using the v2 API, you can:

• Provision and modify clusters: Safely create or update your PostgreSQL deployments on region-specific endpoints.
• Control geographic data safety: Query explicit Backup Locations to determine exactly where your backups are stored and manage them.
• Manage independent backups: Access, filter, and manage your backups as an independent, first-class resource through the dedicated /backups top-level endpoint, making it easier to locate specific restore points.
• Query supported configurations: Retrieve centralized lists of supported PostgreSQL versions to plan and configure your cluster deployments.
• Search and filter resources: Filter clusters by name and state, and filter backups by cluster ID (filter.clusterId), alongside standardized pagination across listing endpoints.

The PostgreSQL v2 APIs are available with the following API endpoints.

Note: For all Frankfurt locations, use the https://postgresql.de-fra.ionos.com/v2 endpoint.

To authenticate with the API, see Authentication. To make your first API call, see Quick Start.

• Storage: Uses SSD Premium as the standard storage type for optimal input/output operations per second (IOPS) performance. Hard Disk Drive (HDD) and SSD Standard storage types are not supported.
• Replication modes: Supports ASYNCHRONOUS and STRICTLY_SYNCHRONOUS replication across cluster instances. STRICTLY_SYNCHRONOUS requires at least three instances and guarantees strong consistency at the cost of potential performance impact in high-latency environments.
• Ensure pattern: Cluster updates use strict replacement logic through PUT endpoints. Provide the full resource object on every call. Fields not included in the payload reset to their defaults rather than retaining their previous values.

DBaaS for PostgreSQL is a fully managed service. IONOS CLOUD grants your database user the widest set of privileges possible without allowing the user to interfere with the automation that keeps the cluster healthy, backed up, and highly available. In practice, your user is not a PostgreSQL superuser, but it can perform most day-to-day database administration tasks.

Note: IONOS CLOUD does not grant SUPERUSER access. The platform handles operations that require a superuser. For the list, see Operations Handled by the Platform.

Initial Database User

When you create a cluster, you provide credentials for one initial database user. The user owns the initial database and the following role attributes apply:

IONOS CLOUD reserves the SUPERUSER, REPLICATION, and BYPASSRLS attributes for the platform and does not grant them to your user.

On PostgreSQL 16 and later, the initial user is also a member, with administrator privilege, of the predefined monitoring roles pg_monitor, pg_read_all_stats, and pg_stat_scan_tables. You can read all statistics and monitoring views, and grant the same access to your own roles.

Add Users and Databases Through the API

Submitting the cluster's credentials object on a cluster update is additive, not a full replacement:

• A new username creates an additional user with access to the specified database. The previously existing user is preserved.
• A new database creates that database and grants the specified user access to it, in addition to any databases the user could already access.
• An existing username updates that user's password. It does not create a duplicate user.
• Omitting credentials entirely from the request leaves all existing users and databases unchanged. This is an exception to the Ensure pattern's usual full-replacement behavior described under Features.

  Manage More Users and Databases With SQL

  For anything beyond adding users and databases, such as granting specific privileges, managing roles, or dropping objects, connect to the cluster and use standard PostgreSQL SQL. For example:

  -- Create a login role (a user) and a database
  CREATE ROLE app_user LOGIN PASSWORD 'a-strong-password';
  CREATE DATABASE app;
  -- Grant database-level privileges
  GRANT CONNECT, TEMPORARY ON DATABASE app TO app_user;
  -- Grant object privileges inside a database
  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_user;
  

  For the complete privilege syntax, see the PostgreSQL Documentation.

  Note: The v1 API also offers dedicated endpoints to manage users and databases.

  Activate Extensions

  You can enable any extension from the curated allowlist with CREATE EXTENSION. This includes widely used extensions such as pg_trgm, citext, pgcrypto, hstore, uuid-ossp, postgis, vector, and timescaledb. Scheduled jobs are available through pg_cron, which you manage with the cron_admin role and which requires no superuser. For the full list and setup instructions, see Activate Extensions. The allowlist excludes extensions that require a superuser, such as file_fdw, and untrusted procedural languages like plpython3u.

  Operations Handled by the Platform

  The following operations require a PostgreSQL superuser. IONOS CLOUD handles them so that a database user cannot disrupt the managed service:

• Changing server configuration directly with ALTER SYSTEM or by editing postgresql.conf. The cluster API and the Data Center Designer expose tunable parameters instead.
• Granting the SUPERUSER, REPLICATION, or BYPASSRLS attributes, and creating roles that hold them.
• Installing extensions or procedural languages that require a superuser.
• Server-side file and operating-system access, such as COPY ... TO/FROM PROGRAM, the pg_read_file function family, and CREATE TABLESPACE.
• Instance-level objects such as event triggers and replication slots.

  Reserved Names

  IONOS CLOUD reserves a small set of names for the platform. You cannot use these names for your own users or databases. Reserved user names include postgres, any name that starts with pg_, replication, admin, root, and sys. Reserved database names include postgres, template0, template1, and information_schema. Any other name is available.

The PostgreSQL v2 API enforces rate limits. If a request exceeds the limit, the API returns HTTP 429 Too Many Requests. Check the Retry-After response header for the number of seconds to wait before retrying.

All list endpoints support offset-based pagination through two query parameters. The endpoints are: Retrieve all Clusters, Retrieve all Backups, Retrieve all BackupLocations, and Retrieve all Versions.

To retrieve the next page, increment offset by the value of limit. Example: offset=100&limit=100 returns elements from 101 to 200.

• Reduce operational overhead: Managed provisioning, scaling, and backups let you focus on your application instead of infrastructure.
• Protect data durability: Continuous Write-Ahead Log (WAL) archiving and point-in-time recovery let you restore a cluster to any moment within the retention window.
• Maintain data residency compliance: Explicit backup location management provides control over where cluster backups are stored, supporting regulatory and data sovereignty requirements.
• Simplify multi-region deployment: Region-specific endpoints reduce management latency and support data locality requirements across Europe and the United States.
• Streamline cluster lifecycle management: The idempotent Ensure pattern lets you apply full desired-state updates without tracking partial changes.

IONOS CLOUD DBaaS PostgreSQL offers PostgreSQL v2 and PostgreSQL v1 API versions. PostgreSQL v2 is the recommended version. It supports multi-region deployments, idempotent cluster management through the Ensure pattern, dedicated backup location management, and improved privilege separation compared to v1.

Important: The PostgreSQL v1 API will be deprecated in an upcoming release. All existing clusters operating on the v1 version are automatically migrated to the v2 version as part of this process. No action is required from you. For more information, see What Changed in v2.

IONOS CLOUD supports PostgreSQL versions 14, 15, 16, 17, and 18, for example 16.4 and 17.2. PostgreSQL follows a yearly major release schedule, and each major version receives 5 years of support after its initial release. IONOS CLOUD DBaaS handles minor version upgrades automatically during maintenance windows. For example, a cluster running 16.4.1 is automatically upgraded to 16.4.2 when the next patch release becomes available. For more information, see Upgrade and Maintenance.

The following tables highlight the key differences between PostgreSQL v1 and v2 APIs, including the changes and their advantages.

General API Architecture and Infrastructure

Cluster Management, Storage, and Networking

Replication and Connection Pooling

Identity and Authentication

Backup and Restore

Observability

All requests to the PostgreSQL v2 API require a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

To generate a token, use IONOS CLOUD Authentication API. The PostgreSQL v2 API supports only token-based authentication (tokenAuth). Basic authentication is not supported.

List supported PostgreSQL versions to confirm your access token works. The following example uses the Berlin (de-txl) endpoint:

curl -X GET "https://postgresql.de-txl.ionos.com/v2/versions" \
  -H "Authorization: Bearer $IONOS_TOKEN" \
  -H "Content-Type: application/json"

A successful response returns HTTP 200 with a list of supported PostgreSQL versions and available upgrade paths. The items array is empty only if no versions are now supported for the endpoint. To connect to a specific region, replace the endpoint host with the corresponding regional host from the Endpoints. Existing integrations that still call the root path remain supported for backward compatibility, and both / and /v2 are routed to the same PostgreSQL v2 backend.

To provision your first cluster, see Deploy a PostgreSQL Cluster.

Use these end-to-end workflows to deploy, connect, operate, and restore resources using the IONOS CLOUD DBaaS PostgreSQL v2 API.

• Deploy a PostgreSQL cluster: Plan your cluster configuration and provision it through to the AVAILABLE state.
• Connect to your PostgreSQL cluster: Connect to a provisioned cluster using its DNS name, credentials, and optional connection pooler.
• Operate a PostgreSQL cluster: Manage a running cluster with day-to-day operations and deprovision it when no longer needed.
• Restore from a backup: Recover cluster data to a specific point in time using Point-in-Time Recovery (PITR) backups.
• Verify backup data residency: Confirm that cluster backups are stored in the expected Object Storage region.

  Note: If an operation returns an error, refer to the response details of each operation for API-specific error codes. For generic HTTP status codes used across IONOS CLOUD APIs, see HTTP Status Codes.

Use this workflow to plan and provision a new PostgreSQL cluster.

Prerequisites

• An access token that authenticates your API requests. For more information, see Authentication.
• The Universally Unique Identifier (UUID) of an existing Virtual Data Center (VDC) (datacenterId) that resides in the same region as your target PostgreSQL endpoint. To create a VDC, use IONOS CLOUD API.
• The identifier of a private Local Area Network (LAN) (lanId) within that VDC. The cluster connects to this LAN during provisioning. To create a LAN, use IONOS CLOUD API.
• A static IP address (primaryInstanceAddress) in Classless Inter-Domain Routing (CIDR) notation that you assign to the primary node. Example: 192.168.2.101/24. The range 10.208.0.0/12 is unavailable.

  Step 1: Plan Configuration

1. Find the backup location: Specify the region where your cluster's backups are stored.
   • API: Retrieve all BackupLocations
   • Action: Browse the list to identify an available backup region.
   • Result: The API returns HTTP 200 with a list of backup locations. Each entry includes an id (UUID) and a location value. Example: eu-central-3. Note the location value to use in properties.backup.location when provisioning the cluster. If _links.next is present, repeat the call with an incremented offset to retrieve the next page.

     Note: For geographic data safety, choose a backup location in a different region from your cluster endpoint. Once set, confirm the location by retrieving the cluster and checking properties.backup.location. The backup location cannot be changed after the cluster is created.

2. Select a PostgreSQL version: Retrieve the list of supported PostgreSQL versions.
   • API: Retrieve all Versions
   • Action: Identify the version that matches your requirements.
   • Result: The API returns HTTP 200 with a list of supported PostgreSQL versions. Each entry includes the version identifier, its lifecycle status (SUPPORTED, RECOMMENDED, or DEPRECATED), and a canUpgradeTo array listing available upgrade paths. Note the version identifier to use for properties.version when provisioning the cluster. If _links.next is present, repeat the call with an incremented offset to retrieve the next page.
3. Choose a replication mode: Select the mode that matches your consistency and availability requirements.
   • ASYNCHRONOUS: The primary instance acknowledges writes before replicas confirm. Use for performance-sensitive workloads where brief data loss on primary failure is acceptable.
   • STRICTLY_SYNCHRONOUS: All instances must confirm writes before the primary acknowledges. Requires a minimum of three instances. Use when strong consistency and zero data loss are required.

     Note:

     • STRICTLY_SYNCHRONOUS may reduce write throughput in high-latency network environments.
     • On primary failure, the cluster automatically promotes a replica. With ASYNCHRONOUS replication, writes not yet propagated to replicas may be lost. With STRICTLY_SYNCHRONOUS replication, all confirmed writes are preserved because every instance acknowledged them before the primary committed.

     Step 2: Provision a Cluster

4. Create the cluster:
   • API: Create Cluster
   • Action: Provide the required fields: name, version, instances (containing count, ram, cores, and storageSize), connection (containing datacenterId, lanId, and primaryInstanceAddress), replicationMode, backup (containing location and retentionDays), maintenanceWindow, and credentials (containing username, password, and database).

     Note:

     • connection.datacenterId and connection.lanId cannot be changed after the cluster is created. Confirm they are correct before submitting this request.
     • For geographic data safety, choose a backup location in a different region from your cluster endpoint. backup.location cannot be changed after the cluster is created.
     • logsEnabled and metricsEnabled are optional. Set either to true to activate log or metrics forwarding.
       • logsEnabled requires the IONOS CLOUD Logging Service to be activated on your contract.
       • metricsEnabled requires the IONOS CLOUD Monitoring Service to be activated on your contract. Activating either service incurs additional costs.

Example request body:

{
  "properties": {
    "name": "cms-prod",
    "version": "16",
    "instances": {
      "count": 3,
      "ram": 8,
      "cores": 4,
      "storageSize": 100
    },
    "connection": {
      "datacenterId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
      "lanId": "2",
      "primaryInstanceAddress": "192.168.2.101/24"
    },
    "replicationMode": "ASYNCHRONOUS",
    "backup": {
      "location": "eu-central-3",
      "retentionDays": 7
    },
    "maintenanceWindow": {
      "dayOfTheWeek": "Sunday",
      "time": "02:00:00"
    },
    "credentials": {
      "username": "my_dbuser",
      "password": "S3cure!Pass",
      "database": "mydb"
    }
  }
}

• Result: The API returns HTTP 201. Note the id: you need it in every subsequent cluster operation. metadata.state starts as PROVISIONING.

  Note:

  • Cluster provisioning is asynchronous. Poll Retrieve Cluster until metadata.state is AVAILABLE. Once available, metadata.dnsName contains the stable hostname for connecting.
  • If metadata.state returns FAILED, the cluster failed to provision. Retrieve the cluster details using Retrieve Cluster and check metadata.statusMessage for the failure reason. Common causes include an invalid datacenterId or lanId, or a primaryInstanceAddress that conflicts with an existing allocation. Correct the configuration and submit a new Create Cluster request. Failed clusters cannot be recovered in place.

Next steps: To connect to your cluster, see Connect to Your PostgreSQL Cluster.

Use this workflow to retrieve the PostgreSQL cluster connection endpoint and connect using your credentials.

Prerequisites

• Ensure the cluster is in the AVAILABLE state.
• You must have the id (UUID) of the cluster. You receive this when you complete the Deploy a PostgreSQL Cluster workflow.
• You must have the credentials.username, credentials.password, and credentials.database set during provisioning.

  Step 1: Retrieve the Connection Details

• API: Retrieve Cluster
• Path Parameter clusterId: The UUID of your cluster.
• Action: Retrieve the cluster to obtain the connection endpoint and credentials.
• Result: The API returns HTTP 200 with the full cluster object. Note metadata.dnsName (the stable hostname), properties.credentials.username, and properties.credentials.database: you need all three in Step 2.

  Step 2: Connect to the Cluster

  Use the following details with any PostgreSQL-compatible client or driver:

  Property	Value
  Host	metadata.dnsName value from Step 1
  Port	5432 (standard PostgreSQL port)
  Database	The database name from credentials.database
  User	The username from credentials.username
  Secure Sockets Layer (SSL) mode	require
  Example connection string:

  postgresql://<username>:<password>@<dnsName>:5432/<database>?sslmode=require
  

  Note: sslmode=require is mandatory. IONOS CLOUD DBaaS PostgreSQL clusters reject unencrypted connections to protect data in transit. If your client omits sslmode=require, the connection attempt fails.

  Step 3: Connect through the Connection Pooler (Optional)

  If connectionPooler is set to TRANSACTION or SESSION on the cluster, the pooler is accessible on the same dnsName. Use your PostgreSQL client's pooler port configuration to connect. Refer to your cluster's connectionPooler property for the configured mode.

• Pool mode: TRANSACTION: Each server connection is released back to the pool after each transaction. Avoid session-level features such as prepared statements and advisory locks in transaction pool mode.

  Note: Connection pooling is most effective for applications that open many short-lived connections. For long-running analytical queries, use a direct connection instead.

Next steps: For day-2 tasks on a running cluster, see Operate a PostgreSQL Cluster.

Use this workflow to perform day-2 tasks on a running cluster.

Note: All configuration changes use Ensure Cluster. Before submitting any update, retrieve the full cluster configuration using Retrieve Cluster and include all required fields in the payload. Any field omitted resets to its default value. After submitting, poll metadata.state until it returns to AVAILABLE.

Prerequisites

• Ensure the cluster is in the AVAILABLE state.
• You must have the id (UUID) of the cluster. You receive this when you complete the Deploy a PostgreSQL Cluster workflow.

  Review Backups

  Backups are read-only PITR copies of your data.
• API: Retrieve all Backups
• Action: Filter by filter.clusterId to scope results to your cluster.
• Result: The API returns HTTP 200 with a paginated list of backups. Each entry includes isActive (whether the backup is usable as a restore point) and the earliestRecoveryTargetTime to latestRecoveryTargetTime window defining the available restore range. To inspect a specific backup in detail, call Retrieve Backup with the backup id. An empty items array means no backups exist yet. If _links.next is present, repeat the call with an incremented offset to retrieve the next page.

  Note: To recover data from a backup, see Restore from a Backup.

  Scale Cluster Resources

  Adjust instance count, CPU, memory, or storage.

• API: Ensure Cluster
• Path Parameter clusterId: The UUID of the cluster.
• Action: Submit the full cluster object with updated instances values (count, ram, cores, storageSize).
• Result: The API returns HTTP 200, confirming the cluster transitions to UPDATING, then back to AVAILABLE. Poll Retrieve Cluster on metadata.state to confirm. If metadata.state returns FAILED, check metadata.statusMessage for the failure reason. Correct the configuration and resubmit the full cluster object.

  Monitor Version Lifecycle

  Periodically check the lifecycle status of the PostgreSQL version your cluster runs on to detect when an upgrade is required.
• API: Retrieve all Versions
• Action: Find the entry matching your cluster's properties.version and read its status field.
• Result: The API returns HTTP 200 with a list of supported PostgreSQL versions. Each entry includes the version identifier and its lifecycle status. Find the entry for your cluster's current version and check status:
  • SUPPORTED or RECOMMENDED: no action needed.
  • DEPRECATED: the version is no longer actively supported. Upgrade to a SUPPORTED or RECOMMENDED version. See Upgrade the PostgreSQL Version in PostgreSQL v2 API Workflows. If _links.next is present, repeat the call with an incremented offset to retrieve the next page.

    Upgrade the PostgreSQL Version

    Move the cluster to a later major or minor version.
• Prerequisite: Use Retrieve all Versions to find the entry for the cluster's current properties.version and check its canUpgradeTo array. Proceed only if the target version is listed. Review backups using Retrieve all Backups to confirm an active restore point exists before upgrading.
• API: Ensure Cluster
• Path Parameter clusterId: The UUID of the cluster.
• Action: Submit the full cluster object with properties.version updated to the target version from canUpgradeTo.
• Result: The API returns HTTP 200, confirming the cluster transitions to UPDATING, then back to AVAILABLE. Version upgrades typically take longer than scale operations. Once available, properties.version reflects the upgraded version. If metadata.state returns FAILED, check metadata.statusMessage for the failure reason. Confirm the target version is listed in canUpgradeTo for the cluster's current version and resubmit the full cluster object with the corrected properties.version. Downgrades are not supported.

Update the Maintenance Window

Change the day or time of the weekly 4-hour maintenance window.

• API: Ensure Cluster
• Path Parameter clusterId: The UUID of the cluster.
• Action: Submit the full cluster object with updated maintenanceWindow values (time in HH:MM:SS format and dayOfTheWeek). Example: time: 02:00:00, dayOfTheWeek: Wednesday.
• Result: The API returns HTTP 200. The new window takes effect from the next scheduled maintenance cycle.

  Deprovision the Cluster

  Warning: Deleting a cluster is irreversible. The cluster and all associated resources are permanently removed. Ensure you have a recent backup before deleting if you may need the data later. Deprovision the cluster when it is no longer needed to release resources.

• API: Delete Cluster
• Path Parameter clusterId: The UUID of the cluster to delete.
• Action: Submit the delete request to permanently remove the cluster and all associated resources.
• Result: The API returns HTTP 202, confirming the delete request is accepted. Deletion is asynchronous. The cluster and all associated resources are permanently removed and cannot be recovered.

  Note: If the cluster remains in DESTROYING longer than expected, retrieve the cluster using Retrieve Cluster and check metadata.statusMessage for the failure reason. If the message is absent or unclear, contact IONOS CLOUD Support and provide the cluster id. Next steps: To recover cluster data from a backup, see Restore from a Backup.

Use this workflow to create a new PostgreSQL cluster from a backup or to restore an existing cluster to a previous state.

Prerequisites

• Ensure the cluster is in the AVAILABLE state.
• You must have the id (UUID) of the cluster. You receive this when you complete the Deploy a PostgreSQL Cluster workflow.
• The cluster must have at least one active backup (isActive: true). You must have the id (UUID) of the backup. You receive this in Step 1 of this workflow after listing backups for your cluster. Note the backup id (sourceBackupId) and an ISO 8601 timestamp within the backup's earliestRecoveryTargetTime to latestRecoveryTargetTime window. Omit the timestamp to restore the full backup.

  Step 1: Find the Backup

• API: Retrieve all Backups
• Action: Filter by filter.clusterId to scope results to your cluster.
• Result: The API returns HTTP 200 with a paginated list of backups. Each entry includes isActive (whether the backup is usable), the earliestRecoveryTargetTime to latestRecoveryTargetTime window defining the available restore range, and the backup id. Note the id and confirm the target timestamp falls within the recovery window before proceeding. If _links.next is present, repeat the call with an incremented offset to retrieve the next page. Choose one of the following restore paths based on your recovery scenario.

  Path 1: Create a New Cluster from a Backup

  Use this path when you want to verify restored data before replacing an existing cluster.
• API: Create Cluster
• Action: Include a restoreFromBackup object in properties with sourceBackupId and optional recoveryTargetDatetime. Example response (HTTP 201):

  {
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "cluster",
  "metadata": {
    "state": "PROVISIONING"
  },
  "properties": {
    "name": "my-restored-cluster"
  }
  }
  

• Result: The API returns HTTP 201. Note the id: you need it to monitor provisioning. metadata.state starts as PROVISIONING.

  Note: Cluster creation is asynchronous. Poll Retrieve Cluster until metadata.state is AVAILABLE. If metadata.state returns FAILED, check metadata.statusMessage for the failure reason. Confirm the sourceBackupId is valid and that the recoveryTargetDatetime falls within the backup's earliestRecoveryTargetTime to latestRecoveryTargetTime window. Correct the configuration and submit a new Create Cluster request.

  Path 2: Restore the Existing Cluster in Place

  Use this path when you must recover the current cluster to an earlier state. This path is destructive and cannot be undone.

• API: Ensure Cluster
• Path Parameter clusterId: The UUID of the cluster to restore.
• Action: Submit the full cluster object with restoreFromBackup.recoveryTargetDatetime (required ISO 8601 timestamp for the target recovery point).
• Result: The API returns HTTP 200, confirming the cluster transitions to UPDATING, then back to AVAILABLE.

  Warning: In-place restore overwrites all current cluster data. This action cannot be undone. If metadata.state returns FAILED, check metadata.statusMessage for the failure reason. Because in-place restore overwrites existing data before the restore completes, the cluster's data state may be indeterminate on failure. Do not retry the restore without first confirming metadata.statusMessage. If the message is absent or unclear, contact IONOS CLOUD Support and provide the cluster id and the timestamp of the failed restore. Next steps: To verify where your cluster's backups are stored, see Verify Backup Data Residency.

Use this workflow to confirm that your cluster's backups are stored in the expected Object Storage region to meet data residency or disaster recovery requirements.

Prerequisites

• An existing PostgreSQL v2 cluster in the AVAILABLE state and its id (UUID). Use Retrieve all Clusters to list clusters if needed.

  Step 1: Find the Cluster's Backup Location

• API: Retrieve Cluster
• Path Parameter clusterId: The UUID of the cluster to inspect.
• Action: Retrieve the cluster to identify where its backups are stored and how long they are retained.
• Result: The API returns HTTP 200 with the full cluster object. Note the properties.backup.location value (example: eu-central-3) and the properties.backup.retentionDays value. You need the location to look up the backup location in Step 2.

  Step 2: Verify the Backup Location

• API: Retrieve BackupLocation
• Path Parameter backupLocationId: Use Retrieve all BackupLocations to find the id that matches the location from Step 1.
• Action: Retrieve the backup location entry to verify its geographic region.
• Result: The API returns HTTP 200 with the backup location object. Confirm the location value meets your GDPR, contractual data residency, or disaster recovery requirements.

  Note: For geographic data safety, ensure the backup location differs from the cluster's own region.

A PostgreSQL (PG) cluster is a unified group of one or more interconnected database instances. It consists of a single primary instance that handles all write operations, along with optional standby replicas that provide high availability. This entity represents the entire logical unit, allowing for the unified management of all its nodes and configurations. Credentials are managed through the cluster resource and are used to provision and manage the cluster's database users. Customers can connect directly to the cluster using standard PostgreSQL tools to create additional users, databases, and access grants. When credentials are supplied, the behavior is additive: a new username creates a new user with cluster-wide access granted to the specified database — the previous user is preserved; a new database creates a new database and grants the specified user access to both the new and any previously accessible databases; an existing username updates the user's password. Unlike other cluster fields, omitting the credentials field leaves all existing users and databases unchanged rather than clearing them. This tag groups all operations for clusters.

Access and manage PITR backups for your PostgreSQL clusters through the IONOS CLOUD API. PITR allows the cluster to be restored to any specific moment within the backup window. Use earliestRecoveryTargetTime to identify the earliest available restore point and latestRecoveryTargetTime to identify the latest. This tag groups all operations for backups.

Query available Object Storage regions for backup storage through the IONOS CLOUD API. For geographic data safety, choose a backup location in a different region from your cluster. Use the location value from the backup locations response when configuring backup.location on your cluster. This tag groups all operations for backuplocations.

Query supported PostgreSQL versions and upgrade paths through the IONOS CLOUD API. Use canUpgradeTo to identify which versions a cluster can be upgraded to and status to filter for SUPPORTED or RECOMMENDED versions for production deployments. This tag groups all operations for versions.