# Get Started with PostgreSQL v2 API

With the IONOS Cloud DBaaS PostgreSQL v2 API, you can create and manage highly available clusters, configure granted users with defined permissions, handle backups through snapshots, and choose from supported versions and instance templates.

To get started with the IONOS Cloud 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\. Upon 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`
* **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`
* **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`
* **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`.
* **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}`
* **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 `PROVISIONED`.
* **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`
* **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}`
* **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`.
* **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>](https://docs.ionos.com/cloud/databases/postgresql/api/v2-api/workflows/view-cluster-verify-backup) workflow.
{% endhint %}

* **Delete cluster:** Delete the cluster by providing its `UUID`.
  * **Endpoint:** `DELETE /clusters/{clusterId}`
  * **Path Parameter:** You must provide the following:
    * `clusterId`: The UUID of the cluster.
  * **Action:** The endpoint permanently removes the cluster resources.
    {% endstep %}
    {% endstepper %}