In-Memory DB v2 API Workflows

The section provides end-to-end workflows for working with the IONOS CLOUD DBaaS In-Memory DB v2 API. Each workflow covers a specific operational scenario:

• Deploy a Cluster: Plan your cluster configuration and provision it through to the AVAILABLE state.
• Connect to Your Cluster: Retrieve the cluster DNS endpoint and connect using your cluster credentials.
• Operate a Cluster: Manage a running cluster with day-to-day operations and deprovision it when no longer needed.
• Restore from a Snapshot: Create a new cluster or restore an existing cluster from a point-in-time snapshot.

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 In-Memory DB 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 In-Memory DB endpoint. To create a VDC, use the 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 the 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 ranges 10.210.0.0/16 and 10.212.0.0/14 are unavailable.

Step 1: Plan Configuration

1. Find the snapshot location: Choose the Object Storage region where you want the cluster to store snapshots.

   • API: Retrieve all SnapshotLocations
   • Action: Note the location value. Example: eu-central-3.

   Note: For geographic data safety, choose a snapshot location in a different region from your cluster endpoint. Once set, confirm the location by retrieving the cluster and checking snapshot.location.

2. Select an In-Memory DB version: Retrieve the list of supported versions to choose the version for your In-Memory DB cluster.

   • API: Retrieve all Versions
   • Action: Note the version you select for your In-Memory DB cluster. The response includes canUpgradeTo for available upgrade paths.

Step 2: Provision a Cluster

Create a new In-Memory DB cluster on the region-specific endpoint for your target location.

• API: Create Cluster
• Action: Provide the required fields: name, version, instances (containing count, cores, and ram), connection (containing datacenterId, lanId, and primaryInstanceAddress), evictionPolicy, snapshot (containing location, retentionDays, and snapshotHours), maintenanceWindow, and credentials. persistenceMode is optional; omitting it applies the service default (None).

Example response (HTTP 201):

{
  "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
  "type": "cluster",
  "metadata": {
    "state": "PROVISIONING",
    "dnsName": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead.in-memory-db.de-fra.ionos.com"
  },
  "properties": {
    "name": "my-cluster",
    "version": "9.0"
  }
}

Note the id and metadata.dnsName from the response for subsequent operations.

Note: Cluster provisioning is asynchronous. Poll Retrieve Cluster until metadata.state is AVAILABLE before proceeding.

Connect to Your Cluster

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

Prerequisites

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

Step 1: Retrieve the Cluster DNS Name

• API: Retrieve Cluster
• Path Parameter {clusterId}: The UUID of the cluster.
• Action: Note metadata.dnsName. Pattern: <clusterId>.in-memory-db.<region>.ionos.com. This is the hostname for connecting to the cluster's primary instance.

Step 2: Connect to the Cluster

Use metadata.dnsName as the hostname together with credentials.username and the plaintext password corresponding to the SHA-256 hash provided in credentials.password.hash during provisioning. For client setup and configuration options, see IONOS CLOUD In-Memory DB Guide.

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. The tasks below are independent and can be performed in any order.

Prerequisites

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

Upgrade the Cluster Version

Trigger an in-place version upgrade by providing a new version value in a PUT request. Only versions listed in canUpgradeTo for the current version are accepted. Downgrades are not supported.

• API: Ensure Cluster
• Path Parameter {clusterId}: The UUID of the cluster.
• Action: Send the full cluster body with the new version value. PUT uses strict replacement logic. All required fields must be present.

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

{
  "id": "e69b22a5-8fee-56b1-b6fb-4a07e4205ead",
  "properties": {
    "name": "my-cluster",
    "version": "9.0",
    "instances": {
      "count": 1,
      "cores": 4,
      "ram": 8
    },
    "connection": {
      "datacenterId": "5a029f4a-72e5-11ec-90d6-0242ac120003",
      "lanId": "2",
      "primaryInstanceAddress": "192.168.2.101/24"
    },
    "persistenceMode": "RDB",
    "evictionPolicy": "allkeys-lru",
    "snapshot": {
      "location": "eu-central-3",
      "retentionDays": 14,
      "snapshotHours": [0, 6, 12, 18]
    },
    "maintenanceWindow": {
      "dayOfTheWeek": "Sunday",
      "time": "02:00:00"
    }
  }
}

Note: Cluster upgrade is asynchronous. Poll Retrieve Cluster until metadata.state is AVAILABLE.

Update Credentials

Update the cluster's database credentials. The specified user is created if it does not exist, or the password is updated if the user already exists. Omitting credentials in a PUT leaves existing credentials unchanged.

• API: Ensure Cluster
• Path Parameter {clusterId}: The UUID of the cluster.
• Action: Send the full cluster body with updated credentials.

Configure Observability

Activate or deactivate log and metrics collection for the cluster.

• API: Ensure Cluster
• Path Parameter {clusterId}: The UUID of the cluster.
• Action: Set logsEnabled and metricsEnabled in the cluster body. If the observability service is not activated on the contract, these settings are accepted but have no effect until the service is activated.

Deprovision the Cluster

Warning: Cluster deletion is irreversible. Ensure you have a recent snapshot 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.

Next steps: To recover cluster data from a snapshot, see Restore from a Snapshot.

Restore from a Snapshot

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

Prerequisites

• An existing snapshot in the same region as the target cluster.
• Path 1 (new cluster): Note the snapshot id (used as sourceSnapshotId). Optionally, note the target time within the snapshot recovery window (recoveryTargetDatetime).
• Path 2 (in-place restore): Note the target time within the snapshot's recovery window (recoveryTargetDatetime). This field is required for in-place restore.

Step 1: Find the Snapshot to Restore From

• API: Retrieve all Snapshots
• Action: Note the snapshot id, its recovery window (earliestRecoveryTargetTime–latestRecoveryTargetTime), and requiredSizeForRestore. Ensure the target cluster has sufficient storage to accommodate requiredSizeForRestore.

Choose one of the following restore paths based on your recovery scenario.

Path 1: Restore to a New Cluster

Use this path to verify restored data before replacing your existing cluster, or to run a parallel environment.

• API: Create Cluster
• Action: Include restoreFromSnapshot.sourceSnapshotId in the request body. Optionally set restoreFromSnapshot.recoveryTargetDatetime to restore from the most recent snapshot at or before that time (defaults to the latest available snapshot). Credentials provided in credentials override those stored in the snapshot.

Example response (HTTP 201):

{
  "id": "f3a91c04-1d2e-47ab-9c3f-50b1967a12de",
  "type": "cluster",
  "metadata": {
    "state": "PROVISIONING",
    "dnsName": "f3a91c04-1d2e-47ab-9c3f-50b1967a12de.in-memory-db.de-fra.ionos.com"
  },
  "properties": {
    "name": "my-restored-cluster",
    "version": "9.0"
  }
}

Note: Cluster creation is asynchronous. Poll Retrieve Cluster until metadata.state is AVAILABLE. Note: Only snapshots from clusters within the same region as the target cluster are eligible for restore.

Path 2: Restore In-Place on an Existing Cluster

Use this path to 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: Include restoreFromSnapshot.recoveryTargetDatetime in the full cluster body to restore from the most recent snapshot at or before that time; the restore source is inferred automatically. The current cluster credentials are replaced by those stored in the snapshot. Example request body (partial):

{
  "properties": {
    "restoreFromSnapshot": {
      "recoveryTargetDatetime": "2020-12-10T13:37:50+01:00"
    }
  }
}

Note: In-place restore is asynchronous. Poll Retrieve Cluster until metadata.state is AVAILABLE. Warning: In-place restore overwrites all current cluster data and may cause brief downtime.