# Get Started with PostgreSQL v2 API

With the <code class="expression">space.vars.ionos\_cloud</code> DBaaS PostgreSQL v2 API, you can create and manage highly available clusters, create a primary database user, manage backups through snapshots, and choose from supported PostgreSQL versions.

To get started with the <code class="expression">space.vars.ionos\_cloud</code> DBaaS PostgreSQL v2 API, follow a sequence of operations to successfully deploy and manage a PostgreSQL database:

1\. Retrieve available configurations, such as versions and backup locations.

2\. Provision a cluster on a region-specific endpoint.

3\. On successful cluster provision, manage clusters and backups.

## Workflow

The workflow describes the complete lifecycle of using the PostgreSQL v2 API, guiding you from initial planning to cluster provisioning, access management, and deprovisioning.

{% stepper %}
{% step %}

#### Plan configuration

Before creating a cluster, you must gather the necessary IDs and supported configuration options to ensure your provisioning payload is valid.

1\. **Find the backup location:** You must specify a location for your backups when creating a cluster. The v2 API explicitly models backup locations for geographic backup safety.

* **Endpoint:** `GET /backup-locations`
* **API:** [<mark style="color:blue;">Retrieve all Backup Locations</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/BackupLocations/operation/backuplocationsGet)
* **Action:** Review the list of locations and note the `id` or `location` for your cluster configuration. Example: `eu-central-3`.

2\. **Select a PostgreSQL version:** Retrieve the supported or recommended PostgreSQL versions to deploy the appropriate version.

* **Endpoint:** `GET /versions`
* **API:** [<mark style="color:blue;">Retrieve all Versions</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Versions/operation/versionsGet)
* **Action:** Identify the version you want to deploy the cluster with. The API response also includes the `canUpgradeTo` version, indicating the version you can upgrade the cluster to.
  {% endstep %}

{% step %}

#### Provision the cluster

Once you have your metadata, you can request the infrastructure.

1\. **Create the cluster:** It is the primary operation to initiate the PostgreSQL deployment.

* **Endpoint:** `POST /clusters`
* **API:** [<mark style="color:blue;">Create Cluster</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Clusters/operation/clustersPost)
* **Payload:** You must provide a JSON object containing metadata and properties. Key properties include:
  * `name`: A unique name for the cluster.
  * `instances`: Provide instance resource details, such as instance `count`, `ram`, `cores`, and `storageSize`.
  * `connection`: Provide the `datacenterId`, `lanId`, and `primaryInstanceAddress`.
  * `maintenanceWindow`: The `time` and `dayOfTheWeek` when the weekly 4-hour-long maintenance can occur.
  * `replicationMode`: The replication mode to use across the instance. Select either `ASYNCHRONOUS`, or `STRICTLY_SYNCHRONOUS`.
  * `credentials`: Provide the `username`, `password`, and the `database` to create the primary database user and the initial database.
  * `backupLocation`: Provide the Object Storage location where the backup will be created. Example: `eu-central-3`.
  * `logsEnabled`: Allow or disallow collection and reporting of cluster logs. If set to `true`, the logs reporting are available.

{% hint style="info" %}
**Prerequisite:** Log reporting is available only when the Observability Logging Service is activated by the user. To activate the Logging Service, use the [<mark style="color:blue;">Ensure Central Logging</mark>](https://api.ionos.com/docs/logging/v1/#tag/Central/operation/centralPut) API with `enabled` parameter set to `true`. Activating the [<mark style="color:blue;">Logging Service</mark>](/cloud/observability/logging-service/overview.md) will incur additional costs.
{% endhint %}

* `metricsEnabled`: Allow or disallow collection and reporting of cluster metrics. If set to `true`, the metrics reporting are available.

{% hint style="info" %}
**Prerequisite:** Metrics reporting is available only when the Observability Monitoring Service is activated by the user. To activate the Monitoring Service, use the [<mark style="color:blue;">Ensure Central Monitoring</mark>](https://api.ionos.com/docs/observability-monitoring/v1/#tag/Central/operation/centralPut) API with the `enabled` parameter set to `true`. Activating the [<mark style="color:blue;">Monitoring Service</mark>](/cloud/observability/monitoring-service/overview.md) will incur additional costs.
{% endhint %}

* **Response:** The API returns the created cluster `id` (UUID) and the `state` as `PROVISIONING`. Save this `id` for all subsequent cluster management.

2\. **Monitor provisioning status:** The cluster is not immediately available. You must poll the API to check its readiness.

* **Endpoint:** `GET /clusters/{clusterId}`
* **API:** [<mark style="color:blue;">Retrieve Cluster</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Clusters/operation/clustersFindById)
* **Path Parameter:** You must provide the following:
  * `clusterId`: The UUID of the cluster.
* **Action:** Check the `state` field. Wait until it transitions from `PROVISIONING` to `AVAILABLE`.
* **Result:** Once provisioned, the API response provides the `dnsName`, such as `pg-010203.postgresql.de-fra.ionos.com`, which is a stable hostname endpoint for accessing your PostgreSQL cluster.
  {% endstep %}

{% step %}

#### Operations and maintenance

During the cluster's life, you can manage its configuration and backups.

1\. **Manage backups:** Backups are read-only Point-in-Time Recovery (PITR) copies of your data. Use this API to view available restore points or backup status.

* **Endpoint:** `GET /backups`
* **API:** [<mark style="color:blue;">Retrieve all Backups</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Backups/operation/backupsGet)
* **Action:** Use robust filtering and standardized pagination, such as filtering by cluster ID (`filter.clusterId`), to view available restore points or backup status.

2\. **Update cluster configuration:** To scale your cluster, change configurations, or maintenance windows, use this API.

* **Endpoint:** `PUT /clusters/{clusterId}`
* **API:** [<mark style="color:blue;">Ensure Cluster</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Clusters/operation/clustersPut)
* **Path Parameter:** You must provide the following:
  * `clusterId`: The UUID of the cluster.
* **Payload:** You must provide the following details:
  * `id`: The UUID of the cluster to be updated.
  * `name`: The name of the cluster.
  * `instances`: Provide instance resource details, such as instance `count`, `ram`, `cores`, and `storageSize`.
  * `connection`: Provide the `datacenterId`, `lanId`, and `primaryInstanceAddress`.
  * `maintenanceWindow`: The `time` and `dayOfTheWeek` when the weekly 4-hour-long maintenance can occur.
  * `replicationMode`: The replication mode to use across the instance. Select either `ASYNCHRONOUS` or `STRICTLY_SYNCHRONOUS`.
  * `backupLocation`: Provide the Object Storage location where the backup will be created. Example: `eu-central-3`.
  * `logsEnabled`: Allow or disallow collection and reporting of cluster logs. If set to `true`, the logs reporting are available.

{% hint style="info" %}
**Prerequisite:** Log reporting is available only when the Observability Logging Service is activated by the user. To activate the Logging Service, use the [<mark style="color:blue;">Ensure Central Logging</mark>](https://api.ionos.com/docs/logging/v1/#tag/Central/operation/centralPut) API with `enabled` parameter set to `true`. Activating the [<mark style="color:blue;">Logging Service</mark>](/cloud/observability/logging-service/overview.md) will incur additional costs.
{% endhint %}

* `metricsEnabled`: Allow or disallow collection and reporting of cluster metrics. If set to `true`, the metrics reporting are available.

{% hint style="info" %}
**Prerequisite:** Metrics reporting is available only when the Observability Monitoring Service is activated by the user. To activate the Monitoring Service, use the [<mark style="color:blue;">Ensure Central Monitoring</mark>](https://api.ionos.com/docs/observability-monitoring/v1/#tag/Central/operation/centralPut) API with the `enabled` parameter set to `true`. Activating the [<mark style="color:blue;">Monitoring Service</mark>](/cloud/observability/monitoring-service/overview.md) will incur additional costs.
{% endhint %}

* **Action:** Submit the cluster object with the required changes.

{% hint style="info" %}
**Note:** The endpoint "ensures" the state, meaning it replaces the full cluster object. Any field not included in the payload will be reset to zero or an empty value; this is not a partial update.
{% endhint %}

#### Cluster deprovision

{% hint style="warning" %}
**Note:** You can deprovision the cluster only to delete it. Else, review the [<mark style="color:blue;">View Cluster and Verify Backups</mark>](/cloud/databases/postgresql/api/v2-api/workflows/view-cluster-verify-backup.md) workflow.
{% endhint %}

* **Delete cluster:** Delete the cluster by providing its `UUID`.
  * **Endpoint:** `DELETE /clusters/{clusterId}`
  * **API:** [<mark style="color:blue;">Delete Cluster</mark>](https://api.ionos.com/docs/postgresql/v2/#tag/Clusters/operation/clustersDelete)
  * **Path Parameter:** You must provide the following:
    * `clusterId`: The UUID of the cluster.
  * **Action:** The endpoint permanently removes the cluster resources.
    {% endstep %}
    {% endstepper %}


---

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

```
GET https://docs.ionos.com/cloud/databases/postgresql/api/v2-api/workflows/get-started.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.