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