Ctrlk
HomeLog InSign UpSend Feedback
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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.

  • 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. 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.

  • 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

    • 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

    • 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

    • 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:

  • 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 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 request. Failed clusters cannot be recovered in place.

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

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

  • 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.

Operate a 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 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

  • 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.

Scale Resources

Adjust instance count, CPU, memory, or storage for a running cluster.

  • 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. 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 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. Confirm an active backup 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.

Example request body (HTTP PUT /clusters/{clusterId}):

Note: Cluster upgrade is asynchronous. Poll Retrieve Cluster 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

  • 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

  • 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.

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 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

  • 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

  • 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):

Note the id from the response. You need it to monitor provisioning.

Note: Resource creation is asynchronous. Poll Retrieve Cluster 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

  • 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.

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

  • 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.

PreviousQuick Start
NextClusters

Last updated

Was this helpful?