Get all deployable databases

GET /deployables

Returns a list of all the types and associated major versions of database deployments that can be provisioned.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployables

Request

Response

200 - Deployable database objects

deployables

array

403 - Invalid token

Get all deployable regions

GET /regions

Returns a list of all the regions that deployments can be provisioned into from the current region. Used to determine region availability for read-only replicas

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/regions

Request

Response

200 - A regions object

regions

array

An array of region ids

403 - Invalid token

Get deployment information

GET /deployments/{id}

Gets the full data that is associated with a deployment. This data includes the ID, name, database type, and version.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A deployment response

deployment

Deployment

403 - Invalid token

Get currently running tasks on a deployment

GET /deployments/{id}/tasks

Obtain a list of tasks currently running or recently run on a deployment. Tasks are ephemeral. Records of successful tasks are shown for 24-48 hours, and unsuccessful tasks are shown for 7-8 days.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/tasks

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - An array of tasks

tasks

array

403 - Invalid token

Get information about a task

GET /tasks/{id}

Get information about a task and its status. Tasks themselves are persistent so old tasks can be consulted as well as running tasks.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/tasks/:task_id

Request

Path Parameters

id

Required *

string

Task ID

Query Parameters

Response

200 - A task

task

Task

303 - A completed task redirects to the associated resource.

task

Task

403 - Invalid token

Get information about a backup

GET /backups/{backup_id}

Get information about a backup, such as creation date.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/backups/:backup_id

Request

Path Parameters

backup_id

Required *

string

Backup ID

Query Parameters

Response

200 - A backup response

backup

Backup

403 - Invalid token

Get currently available backups from a deployment

GET /deployments/{id}/backups

Get details of all currently available backups from a deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/backups

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - An array of backups

backups

array

403 - Invalid token

Initiate an on-demand backup

POST /deployments/{id}/backups

Signal the platform to create an on-demand backup for the specified deployment. The returned task can be polled to track progress of the backup as it takes place.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/backups

Auditing

Calling this method generates the following auditing event.

  • <service_id>.backup-ondemand.create

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

422 - An error message response

errors

object

Get earliest point-in-time-recovery timestamp

GET /deployments/{id}/point_in_time_recovery_data

Returns the earliest available time for point-in-time-recovery in ISO8601 UTC format. PostgreSQL and EnterpriseDB only.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/point_in_time_recovery_data

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - The earliest point-in-time-recovery time

earliest_point_in_time_recovery_time

string

403 - Invalid token

404 - not found

Get currently available scaling groups from a deployment

GET /deployments/{id}/groups

Scaling groups represent the various resources that are allocated to a deployment. This command allows for the retrieval of all of the groups for a particular deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployables/:deployable_id/groups

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - An array of scaling groups

groups

array

403 - Invalid token

Get default scaling groups for a new deployment

GET /deployables/{type}/groups

Scaling groups represent the various resources allocated to a deployment. When a new deployment is created, there are a set of defaults for each database type. This endpoint returns them for a particular database.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployables/:type/groups

Request

Path Parameters

type

Required *

string

Database type name

Query Parameters

host_flavor

string

When a host_flavor of 'multitenant' is included with the request, IBM Cloud Database's new shared compute groups will be returned

Response

200 - An array of scaling groups

groups

array

403 - Invalid token

Set scaling values on a specified group.

PATCH /deployments/{id}/groups/{group_id}

Set scaling value on a specified group. Can only be performed on is_adjustable=true groups. Values set are for the group as a whole and resources are distributed amongst the group. Values must be greater than or equal to the minimum size and must be a multiple of the step size.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • PATCH /v4/ibm/deployments/:deployment_id/groups/:group_id

Request

Request Body

Scaling group settings

Path Parameters

id

Required *

string

Deployment ID

group_id

Required *

string

Group Id

Query Parameters

Response

202 - A task which is being run to scale the deployment

task

Task

403 - Invalid token

422 - An error message response

errors

object

Get the autoscaling configuration from a deployment

GET /deployments/{id}/groups/{group_id}/autoscaling

The Autoscaling configuration represents the various conditions that control autoscaling for a deployment. This command allows for the retrieval of all autoscaling conditions for a particular deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/groups/:group_id/autoscaling

Request

Path Parameters

id

Required *

string

Deployment ID

group_id

Required *

string

Group ID

Query Parameters

Response

200 - An object containing autoscaling conditions

autoscaling

AutoscalingGroup

403 - Invalid token

404 - Not Found

Set the autoscaling configuration from a deployment

PATCH /deployments/{id}/groups/{group_id}/autoscaling

Enable, disable, or set the conditions for autoscaling on your deployment. Memory, disk, and CPU (if available) can be set separately and are not all required.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • PATCH /v4/ibm/deployments/:deployment_id/groups/:group_id/autoscaling

Auditing

Calling this method generates the following auditing event.

  • <service_id>.autoscaling.update

Request

Request Body

Autoscaling configuration

autoscaling

AutoscalingSetGroup

autoscaling

Required *

object

Path Parameters

id

Required *

string

Deployment ID

group_id

Required *

string

Group ID

Query Parameters

Response

200 - A task which is being run to configure autoscaling

task

Task

403 - Invalid token

404 - Not Found

Creates a database-level user

POST /deployments/{id}/users

Creates a user in the database that can access the database through a connection.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/users

Auditing

Calling this method generates the following auditing event.

  • <service_id>.user.create

Request

Request Body

Parameters for creating the user

user

object

username

string

Username for new user

password

string

Password for new user

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

202 - A task which is being run to create the user

task

Task

403 - Invalid token

422 - An error message response

errors

object

Set database-level user's password

PATCH /deployments/{id}/users/{username}

Sets the password of a database-level user.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • PATCH /v4/ibm/deployments/:deployment_id/users/:user_id

Auditing

Calling this method generates the following auditing event.

  • <service_id>.user-password.update

Request

Request Body

New Password Details

user

object

password

string

Path Parameters

id

Required *

string

Deployment ID

username

Required *

string

User ID

Query Parameters

Response

200 - A task which is being run to set the user password

task

Task

403 - Invalid token

422 - An error message response

errors

object

Deletes a database-level user

DELETE /deployments/{id}/users/{username}

Removes a database-level user from the deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • DELETE /v4/ibm/deployments/:deployment_id/users/:user_id

Auditing

Calling this method generates the following auditing event.

  • <service_id>.user.delete

Request

Path Parameters

id

Required *

string

Deployment ID

username

Required *

string

Username

Query Parameters

Response

202 - A task which is being run to delete the user

task

Task

403 - Invalid token

422 - An error message response

errors

object

Discover connection information for a deployment for a user with an endpoint type.

GET /deployments/{id}/users/{user_id}/connections/{endpoint_type}

Discover connection information for a deployment for a user with an endpoint type.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/users/:user_id/connections/:endpoint_type

Request

Path Parameters

id

Required *

string

Deployment ID

user_id

Required *

string

User ID

endpoint_type

Required *

string

Endpoint Type. The endpoint must be enabled on the deployment before its connection information can be fetched.

Query Parameters

certificate_root

string

Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Response

200 - A Connection

connection

object

403 - Invalid token

Discover connection information for a deployment for a user with substitutions and an endpoint type.

POST /deployments/{id}/users/{user_id}/connections/{endpoint_type}

Discover connection information for a deployment for a user. Behaves the same as the GET method but substitutes the provided password parameter into the returned connection information.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/users/:user_id/connections/:endpoint_type

Request

Request Body

Optional parameters to be substituted into the response

password

string

Password to be substituted into the response

certificate_root

string

Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Path Parameters

id

Required *

string

Deployment ID

user_id

Required *

string

User ID

Query Parameters

Response

200 - A Connection

connection

object

403 - Invalid token

422 - An error message response

errors

object

Discover user name and password information for a deployment for a user with an endpoint type.

GET /deployments/{id}/users/{user_id}/

Only for Redis v5 and prior: Discover connection information for a deployment for a user with an endpoint type.

Request

Path Parameters

id

Required *

string

Deployment ID

user_id

Required *

string

User ID

endpoint_type

Required *

string

Endpoint Type. The endpoint must be enabled on the deployment before its connection information can be fetched.

Query Parameters

Response

200 - User

id

string

ID of the task.

resource_type

string

The resource type of the task

description

string

Human-readable description of the task.

status

string

The status of the task.

deployment_id

string

ID of the deployment the task is being performed on.

progress_percent

integer

Indicator as percentage of progress of the task.

created_at

string

Date and time when the task was created.

500 - Not Found

Discover connection information for a deployment for a user.

GET /deployments/{id}/users/{user_id}/connections

Discover connection information for a deployment for a user.

Request

Path Parameters

id

Required *

string

Deployment ID

user_id

Required *

string

User ID

Query Parameters

certificate_root

string

Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Response

200 - A Connection

connection

object

403 - Invalid token

Discover connection information for a deployment for a user with substitutions.

POST /deployments/{id}/users/{user_id}/connections

Discover connection information for a deployment for a user. Behaves the same as the GET method but substitutes the given password parameter into the returned connection information.

Request

Request Body

Optional parameters to be substituted into the response

password

string

Password to be substituted into the response

certificate_root

string

Optional certificate root path to prepend certificate names. Certificates would be stored in this directory for use by other commands.

Path Parameters

id

Required *

string

Deployment ID

user_id

Required *

string

User ID

Query Parameters

Response

200 - A Connection

connection

object

403 - Invalid token

422 - An error message response

errors

object

Retrieve the allowlisted addresses and ranges for a deployment.

GET /deployments/{id}/whitelists/ip_addresses

Retrieve the allowlisted addresses and ranges for a deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/whitelists/ip_addresses

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - An allowlist

ip_addresses

array

An array of allowlist entries

403 - Invalid token

422 - An error message response

errors

object

Replace the allowlist for a deployment.

PUT /deployments/{id}/whitelists/ip_addresses

Replace the allowlist for a deployment. This action overwrites all existing entries, so when you modify the allowlist via a GET/update/PUT, provide the GET response's ETag header value in this endpoint's If-Match header to ensure that changes that are made by other clients are not accidentally overwritten.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • PUT /v4/ibm/deployments/:deployment_id/whitelists/ip_addresses

Auditing

Calling this method generates the following auditing event.

  • <service_id>.whitelisted-ips-list.update

Request

Request Body

Whitelist

New allowlist

ip_addresses

array

An array of allowlist entries

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

202 - A task which is being run to add the allowlist entry

task

Task

403 - Invalid token

422 - An error message response

errors

object

Add an address or range to the allowlist for a deployment.

POST /deployments/{id}/whitelists/ip_addresses

Add an address or range to the allowlist for a deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/whitelists/ip_addresses

Request

Request Body

New allowlist Entry

ip_address

WhitelistEntry

address

string

An IPv4 address or a CIDR range (netmasked IPv4 address)

description

string

A human readable description of the address or range for identification purposes.

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

202 - A task which is being run to add the allowlist entry

task

Task

403 - Invalid token

422 - An error message response

errors

object

Delete an address or range from the allowlist of a deployment.

DELETE /deployments/{id}/whitelists/ip_addresses/{ipaddress}

Delete an address or range from the allowlist of a deployment.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • DELETE /v4/ibm/deployments/:deployment_id/whitelists/ip_addresses/:ip_address_id

Request

Path Parameters

id

Required *

string

Deployment ID

ipaddress

Required *

string

An IPv4 address or a CIDR range (netmasked IPv4 address)

Query Parameters

Response

202 - A task which is being run to delete the allowlist entry

task

Task

403 - Invalid token

422 - An error message response

errors

object

Kill connections to a PostgreSQL or EnterpriseDB deployment

DELETE /deployments/{id}/management/database_connections

Closes all the connections on a deployment. Available for PostgreSQL and EnterpriseDB ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • DELETE /v4/ibm/deployments/:deployment_id/management/database_connections

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

Sync files uploaded to Elasticsearch deployment

POST /deployments/{id}/elasticsearch/file_syncs

Starts a task that writes files to disk. Available for Elasticsearch ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/elasticsearch/file_syncs

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

Create a new logical replication slot

POST /deployments/{id}/postgresql/logical_replication_slots

Creates a new logical replication slot on the specified database. For use with PostgreSQL, EnterpriseDB, and wal2json only.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/postgresql/logical_replication_slots

Request

Request Body

LogicalReplicationSlot

Defines the logical replication slot. All fields are required.

logical_replication_slot

object

name

string

name of the replication slot

database_name

string

name of the database the replication slot is created on

plugin_type

string

creating a replication slot is only supported for use with wal2json

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

Delete a logical replication slot

DELETE /deployments/{id}/postgresql/logical_replication_slots/{name}

Deletes a logical replication slot from a database. For use with PostgreSQL, EnterpriseDB, and wal2json only.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • DELETE /v4/ibm/deployments/:deployment_id/postgresql/logical_replication_slots/:name

Request

Path Parameters

id

Required *

string

Deployment ID

name

Required *

string

Name of the logical replication slot

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

Change your database configuration

PATCH /deployments/{id}/configuration

Change your database configuration. Available for PostgreSQL, EnterpriseDB, and Redis ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • PATCH /v4/ibm/deployments/:deployment_id/configuration

Request

Request Body

SetConfiguration

Database configuration

configuration

Required *

object

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

Get the schema of the database configuration

GET /deployments/{id}/configuration/schema

Get the schema of the database configuration. Available for PostgreSQL and Redis ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/configuration/schema

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A database configuration schema

schema

ConfigurationSchema

Database Configuration Schema

403 - Invalid token

404 - not found

Get read-only replica information

GET /deployments/{id}/remotes

Get the read-only replicas associated with a deployment. Available for PostgreSQL and EnterpriseDB ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • GET /v4/ibm/deployments/:deployment_id/remotes

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A remotes object

remotes

Remotes

Remotes

403 - Invalid token

404 - not found

Modify read-only replication on a deployment

PATCH /deployments/{id}/remotes

Promote a read-only remote replica to leader by calling with leader set to an empty string. Available for PostgreSQL and EnterpriseDB ONLY.

Request

Request Body

Parameters for promoting a read-only replica

remotes

object

leader

string

Leader should be an empty string

skip_initial_backup

boolean

Option to restore instance without taking a backup once data is restored. Allows restored deployment to be available sooner.

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

422 - promotion is the only feature supported and must be requested as an empty string

Resync read-only replica

POST /deployments/{id}/remotes/resync

Reinitialize a read-only replica. Available for PostgreSQL and EnterpriseDB ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/remotes/resync

Request

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

Promote read-only replica to a full deployment

POST /deployments/{id}/remotes/promotion

Promote a read-only replica or upgrade and promote a read-only replica. Available for PostgreSQL and EnterpriseDB ONLY.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • POST /v4/ibm/deployments/:deployment_id/remotes/promotion

Request

Request Body

SetPromotion

Parameters for promoting a read-only replica

Promotion

Required *

object

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

433 - An error message response from sending invalid body parameters.

errors

object

Upgrade your database version

PATCH /deployments/{id}/version

Upgrade your database version. See version upgrade documentation for details

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

  • PATCH /v4/ibm/deployments/:deployment_id/version

Request

Request Body

SetInplaceVersionUpgrade

In-place version upgrade

version

Required *

string

a database version

Path Parameters

id

Required *

string

Deployment ID

Query Parameters

skip_backup

boolean

(Optional, Boolean) Whether to skip taking a backup before upgrading the database version. This is only applicable for supported database types. To learn more, refer to the version upgrade documentation.

expiration_datetime

string

The expiration_datetime must be in the ISO8601 timestamp format and between 5 minutes and 24 hours from now. It allows you to specify how long to wait for the job to start before the upgrade is cancelled.

Response

200 - A task

task

Task

403 - Invalid token

404 - not found

422 - An error message response

errors

object