> 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/api-reference/databases/v2-1/mariadb-api-workflows.md). # MariaDB API Workflows Use these end-to-end workflows to deploy, connect, operate, and restore resources using the IONOS CLOUD MariaDB API. 1. **Deploy a cluster:** Plan your cluster configuration and provision it through to the `AVAILABLE` state. 2. **Connect to your cluster:** Connect to a provisioned cluster using its DNS name and credentials. 3. **Operate a cluster:** Manage a running cluster with day-to-day operations and deprovision it when no longer needed. 4. **Restore from a backup:** Recover cluster data to a specific point in time using PITR backups. 5. **Verify backup data residency:** Confirm that your cluster's 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](https://docs.ionos.com/cloud/reference/get-started#http-status-codes). ### Deploy a Cluster Use this workflow to plan and provision a new cluster. #### Prerequisites * An access token that authenticates your API requests. For more information, see [Authentication](#tag/Authentication). * The Universally Unique Identifier (UUID) of an existing Virtual Data Center (VDC) (`datacenterId`) that resides in the same region as your target endpoint. To create a VDC, use [IONOS CLOUD API](https://api.ionos.com/docs/cloud/v6/#tag/Data-centers). The VM you create is counted against the quota allocated in your contract. * Ensure you are working within a provisioned VDC that contains at least one virtual machine from which to access the database. * 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](https://api.ionos.com/docs/cloud/v6/#tag/LANs). * A static IP address (`primaryInstanceAddress`) in Classless Inter-Domain Routing (CIDR) notation that you assign to the primary instance. Example: `192.168.2.101/24`. The ranges `10.208.0.0/12`, `10.233.0.0/18`, `10.233.64.0/18`, and `192.168.230.0/24` are unavailable. #### Step 1: Plan Configuration 1. **Find a backup location:** Specify the Object Storage region where your cluster's backups are stored. * **API:** [Retrieve all BackupLocations](#tag/BackupLocations/operation/backuplocationsGet) * **Action:** Browse the list to identify the required backup location. * **Result:** The API returns HTTP `200` with a list of available backup locations. Each entry includes an `id` (UUID) and a `properties.location` value. Note the `properties.location` value to use as `properties.backup.location` when provisioning. Example: `eu-central-3`. If `_links.next` is present, repeat the call with an incremented `offset` to retrieve the next page. > **Note:** For geographic data safety, consider choosing a backup location that differs from the cluster's own region. Once set, confirm the location by retrieving the cluster and checking `properties.backup.location`. 2. **Select a MariaDB version:** Retrieve the list of supported MariaDB versions. * **API:** [Retrieve all Versions](#tag/Versions/operation/versionsGet) * **Action:** Identify the version that matches your requirements. * **Result:** The API returns HTTP `200` with a list of supported versions. Each entry includes the version identifier, its lifecycle `status` (`BETA`, `SUPPORTED`, `RECOMMENDED`, or `DEPRECATED`), and a `canUpgradeTo` array. Note the version identifier to use for `properties.version` when provisioning. If `_links.next` is present, repeat the call with an incremented `offset` to retrieve the next page. #### Step 2: Provision a Cluster 1. **Create the cluster:** * **API:** [Create Cluster](#tag/Clusters/operation/clustersPost) * **Action:** Provide a request body with a `properties` object containing the required fields: `name`, `version`, `instances` (containing `count`, `ram`, `cores`, and `storageSize`), `connection` (containing `datacenterId`, `lanId`, and `primaryInstanceAddress`), `maintenanceWindow`, `backup` (containing `location` from Step 1 and `retentionDays`), and `credentials` (containing `username`, `password`, and `database`). Example request body: ```json { "properties": { "name": "my-mariadb-cluster", "version": "10.6", "instances": { "count": 1, "ram": 4, "cores": 2, "storageSize": 20 }, "connection": { "datacenterId": "b2e87f8a-0d6d-4b6e-9c1a-3f5e7d9a1c2e", "lanId": "1", "primaryInstanceAddress": "192.168.1.100/24" }, "maintenanceWindow": { "dayOfTheWeek": "Sunday", "time": "02:00:00" }, "backup": { "location": "eu-central-3", "retentionDays": 7 }, "credentials": { "username": "dbadmin", "password": "S3cure!Pass", "database": "mydb" } } } ``` * **Result:** The API returns HTTP `201` with the cluster object, including the cluster `id` and `metadata.state: PROVISIONING`. Note the `id` from the response. You need it in every subsequent operation. > **Note:** Setting `logsEnabled` or `metricsEnabled` to `true` may require the corresponding IONOS CLOUD observability service to be available on the contract. > > * Cluster provisioning is asynchronous. Poll [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) until `metadata.state` is `AVAILABLE`. > * Once `AVAILABLE`, `metadata.dnsName` contains the stable hostname for accessing your cluster. > * If `metadata.state` returns `FAILED`, the cluster failed to provision. Check `metadata.statusMessage` for the failure reason. Common causes include an invalid `datacenterId` or `lanId`, a `primaryInstanceAddress` that conflicts with an existing allocation, or insufficient storage quota. Correct the configuration and submit a new [Create Cluster](#tag/Clusters/operation/clustersPost) request. Failed clusters cannot be recovered in place. **Next steps:** To connect to your cluster, see [Connect to Your Cluster](#tag/MariaDB-API-Workflows). ### Connect to Your Cluster Use this workflow to retrieve the 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 from the Deploy step. * You must have the `credentials.username`, `credentials.password`, and `credentials.database` set during provisioning. #### Step 1: Retrieve the Connection Details * **API:** [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) * **Path Parameter `clusterId`:** The UUID of your cluster. * **Action:** Retrieve the cluster to obtain the connection endpoint. * **Result:** The API returns HTTP `200` with the full cluster object. Note `metadata.dnsName`. You need it in Step 2. #### Step 2: Connect to the Cluster Use the following details with any MariaDB-compatible client or driver: | Property | Value | | ------------ | --------------------------------------------- | | **Host** | `metadata.dnsName` value from Step 1 | | **Port** | `3306` (default) | | **Database** | The database name from `credentials.database` | | **User** | The username from `credentials.username` | **Next steps:** For day-2 tasks on a running cluster, see [Operate a Cluster](#tag/MariaDB-API-Workflows). ### Operate a Cluster Use this workflow to perform day-2 tasks on a running cluster. > **Note:** All configuration changes use [Ensure Cluster](#tag/Clusters/operation/clustersPut). Before submitting any update, retrieve the full cluster configuration using [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) and include all required fields in the payload. Any field omitted is set to its schema default or cleared to empty — it does not retain its previous 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 from the Deploy step. *(Each task is independent. Perform in any order.)* #### Review Backups Backups are PITR copies of your cluster's binary logs and periodic full snapshots. * **API:** [Retrieve all Backups](#tag/Backups/operation/backupsGet) * **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 `earliestRecoveryTargetTime` and `latestRecoveryTargetTime`. The values define the usable recovery window for Point-in-Time Recovery. 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](#tag/MariaDB-API-Workflows). #### Scale Resources Adjust instance count, CPU, memory, or storage for a running cluster. * **API:** [Ensure Cluster](#tag/Clusters/operation/clustersPut) * **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`. The cluster transitions to `UPDATING`, then back to `AVAILABLE`. Poll [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) on `metadata.state` to confirm. If `metadata.state` returns `FAILED`, check `metadata.statusMessage` for the reason. Correct the configuration and resubmit. #### Upgrade Version Trigger an in-place version upgrade by providing a new version value. Only versions listed in `canUpgradeTo` are accepted. Downgrades are not supported. * **Prerequisite:** Check `canUpgradeTo` for the current version using [Retrieve all Versions](#tag/Versions/operation/versionsGet). Confirm an active backup exists before upgrading. * **API:** [Ensure Cluster](#tag/Clusters/operation/clustersPut) * **Path Parameter `clusterId`:** The UUID of the cluster. * **Action:** Submit the full cluster object with `properties.version` updated to the target version from `canUpgradeTo`. Example request body (HTTP `PUT /clusters/{clusterId}`): ```json { "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead", "properties": { "name": "my-mariadb-cluster", "version": "11.8", "instances": { "count": 2, "ram": 4, "cores": 2, "storageSize": 50 }, "connection": { "datacenterId": "5a029f4a-72e5-11ec-90d6-0242ac120003", "lanId": "2", "primaryInstanceAddress": "192.168.2.101/24" }, "maintenanceWindow": { "time": "02:00:00", "dayOfTheWeek": "Monday" }, "backup": { "location": "eu-central-3", "retentionDays": 90 } } } ``` > **Note:** Cluster upgrade is asynchronous. Poll [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) until `metadata.state` is `AVAILABLE`. * **Result:** The API returns HTTP `200`. The cluster transitions to `UPDATING`, then `AVAILABLE`. If `metadata.state` returns `FAILED`, check `metadata.statusMessage` for the reason. Correct the configuration and resubmit. #### Update Maintenance Window The maintenance window defines a weekly four-hour period when IONOS CLOUD may apply updates to your cluster. * **API:** [Ensure Cluster](#tag/Clusters/operation/clustersPut) * **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`). * **Result:** The API returns HTTP `200`. The new window takes effect from the next scheduled 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](#tag/Clusters/operation/clustersDelete) * **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 was accepted. Deletion is asynchronous. The cluster and all associated resources are permanently removed and cannot be recovered. **Next steps:** To recover cluster data from a backup, see [Restore from a Backup](#tag/MariaDB-API-Workflows). ### Restore from a Backup Use this workflow to create a new 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 Cluster](#tag/MariaDB-API-Workflows) workflow. * For Path 1 (new cluster from backup): You must have the `id` (UUID) of a backup from Step 1. For Path 2 (in-place restore): a backup `id` is not required — the restore source is inferred from the cluster's own backups. #### Step 1: Find the Backup * **API:** [Retrieve all Backups](#tag/Backups/operation/backupsGet) * **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 `earliestRecoveryTargetTime`, `latestRecoveryTargetTime`, 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. #### Step 2: Restore the Cluster Choose one of the following restore paths based on your recovery scenario. #### Path 1: Create a New Cluster from a Backup Use this path to verify restored data before replacing your existing cluster, or to run a parallel environment. **Prerequisites:** The `id` of the backup (`sourceBackupId`) from Step 1. Optionally, a target ISO 8601 timestamp within the backup's recovery window. Omit the timestamp to restore the full backup. * **API:** [Create Cluster](#tag/Clusters/operation/clustersPost) * **Action:** Include a `restoreFromBackup` object in `properties` with `sourceBackupId` and optional `recoveryTargetDatetime`. * **Result:** The API returns HTTP `201` with the new cluster object, including the cluster `id` and `metadata.state: PROVISIONING`. Example response (HTTP `201`): ```json { "id": "f3b4c5d6-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "type": "cluster", "metadata": { "state": "PROVISIONING" }, "properties": { "name": "my-restored-cluster" } } ``` Note the `id` from the response. You need it to monitor provisioning. > **Note:** Resource creation is asynchronous. Poll [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) until `metadata.state` is `AVAILABLE`. If `metadata.state` returns `FAILED`, check `metadata.statusMessage` for the reason. Correct the configuration and resubmit. #### Path 2: Restore the Existing Cluster in Place Use this path to recover the current cluster to an earlier state. This path is destructive and cannot be undone. **Prerequisites:** A target ISO 8601 timestamp (`recoveryTargetDatetime`) within the backup's recovery window. The restore source is inferred from the cluster's own backups: `sourceBackupId` is not required and must not be included. * **API:** [Ensure Cluster](#tag/Clusters/operation/clustersPut) * **Path Parameter `clusterId`:** The UUID of the cluster to restore. * **Action:** Submit the full cluster object with `restoreFromBackup.recoveryTargetDatetime` set to the target ISO 8601 timestamp. * **Result:** The API returns HTTP `200`. The cluster transitions to `UPDATING`, then `AVAILABLE`. If `metadata.state` returns `FAILED`, check `metadata.statusMessage` for the reason. Correct the configuration and resubmit. > **Warning:** In-place restore overwrites all current cluster data. This action cannot be undone. **Next steps:** To verify where your cluster's backups are stored, see [Verify Backup Data Residency](#tag/MariaDB-API-Workflows). ### Verify Backup Data Residency Use this workflow to verify that your cluster's backups are stored in the expected location. #### Prerequisites * Ensure the cluster is in the `AVAILABLE` state. * You must have the `id` (UUID) of the cluster. #### Step 1: Find the Cluster's Backup Location * **API:** [Retrieve Cluster](#tag/Clusters/operation/clustersFindById) * **Path Parameter `clusterId`:** The UUID of the cluster to inspect. * **Action:** Retrieve the cluster to identify the Object Storage region where its backups are stored. * **Result:** The API returns HTTP `200` with the full cluster object. Note `properties.backup.location`. Example: `eu-central-3`. > **Note:** For geographic data safety, consider choosing a backup location that differs from the cluster's own region. --- # 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/api-reference/databases/v2-1/mariadb-api-workflows.md?ask=&goal= ``` `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.