IBM Cloud Hyper Protect DBaaS CLI plug-in

Hyper Protect DBaaS is deprecated. As of 15 April 2023, you can't create new instances, and access to free instances will be removed. Existing paid instances are supported until 30 November 2023. Existing instances will be deleted on 1 March 2024.

This CLI version 2.0. requires the input parameter --output json to return JSON output in order to align with other CLI plugins. This may break running automations. If you still use version 1.x (which is deprecated), leave out this option in your commands. Another change in version 2.0 is that the command names no longer contain -list and -show (for example, ibmcloud dbaas cluster-show is now ibmcloud dbaas cluster). The old command names are deprecated, although they can still work.

Use the IBM Cloud® Hyper Protect DBaaS CLI plug-in to get information about your cluster, databases, users, and nodes, list and download log files, scale resources, update configurations, back up and restore your databases, and check task status.

Prerequisites

Install the IBM Cloud CLI. IBM Cloud CLI requires Java SDK 1.7.0. The prefix for running commands by using the IBM Cloud CLI is ibmcloud. In the terminal, you're notified when updates to the ibmcloud CLI and plug-ins are available. Be sure to keep your CLI up-to-date so that you can use all the available commands and flags.
Install the IBM Cloud Hyper Protect DBaaS CLI plug-in. See Installing the Hyper Protect DBaaS for MongoDB CLI plug-in or Installing the Hyper Protect DBaaS for PostgreSQL CLI plug-in for detailed instructions. If you want to view the current version of your Hyper Protect DBaaS CLI plug-in, run ibmcloud plugin show dbaas.

CLI plug-in usage command

`ibmcloud dbaas help`

This command displays a list of DBaaS commands.

ibmcloud help dbaas

In the returned list, for some of the commands, you can see two command names, for example, cluster, cluster-show and databases, databases-list. The ones with -show and -list are old command names, which are deprecated but can still work. We recommend using the new commands without -list and -show, as documented in the following sections.

Cluster commands

`ibmcloud dbaas cluster`

This command shows the detailed information about a database cluster, including information about each node.

ibmcloud dbaas cluster RESOURCE_NAME [--output json]

Command option

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long. To find the resource name, use the IBM Cloud command ibmcloud resource service-instances.
--output: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas resource-scale`

This command scales the cluster resources (disk, RAM, or vCPU). For the valid value range, see the value table (the same for MongoDB and PostgreSQL).

ibmcloud dbaas resource-scale RESOURCE_NAME [--cpu|-c NUM_CPU] [--memory|-m MEM_GIB] [--storage|-s STORAGE_GIB] [--force] [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--cpu value: Total number of dedicated CPU cores.
--memory value: Total memory allocation in GiB. For example, --memory 4.
--storage value: Total storage allocation in GiB. For example, --storage 10.
--force: Force scaling without the y/N confirmation.
--output: Use the --output option with value json to format output in JSON.

Database command

`ibmcloud dbaas databases`

This command lists all the databases on the cluster.

ibmcloud dbaas databases RESOURCE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output: Use the --output option with value json to format output in JSON.

Database configuration commands (for PostgreSQL)

`ibmcloud dbaas configuration`

This command shows database configuration details.

ibmcloud dbaas configuration RESOURCE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas configuration-update`

This command sends changes from the JSON file or JSON string to update the database configuration.

ibmcloud dbaas configuration-update RESOURCE_NAME [@JSON_FILE | JSON_STRING] [-f | --force] [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.

The configuration parameters are all integers. Don't specify the unit in the JSON file or string.

@JSON_FILE

The JSON file that contains the database configuration. For example:

ibmcloud dbaas configuration-update MyDBaaSIns03 @./conf.json

Content in the JSON file:

{
    "configuration":{
        "max_locks_per_transaction":150,
        "deadlock_timeout":1500,
        "shared_buffers":256,
        "max_connections":115
        
    }
}

If you want to update only one of the settings, you can just specify the one setting that you want to update in the file. For example:

{
    "configuration":{
        "max_locks_per_transaction":150
    }
}

JSON_STRING

The parameter changes to send to the JSON file. For example, '{"configuration":{"max_locks_per_transaction":150}}' (for Windows, use "{\"configuration\": {\"max_locks_per_transaction\": 150}}"). You can use the ibmcloud dbaas configuration command to get a list of the configurable parameters.

-f, --force

Forces the configuration update without prompting for confirmation.

--output

Use the --output option with value json to format output in JSON.

Database user commands

`ibmcloud dbaas users`

This command lists all the database users.

ibmcloud dbaas users RESOURCE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas user`

This command shows details about a database user.

ibmcloud dbaas user RESOURCE_NAME AUTHDB_USER_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
AUTHDB_USER_NAME: The user name of the user to get details about. You can use the ibmcloud dbaas users command to get a list of users for a cluster.
--output: Use the --output option with value json to format output in JSON.

Log commands

`ibmcloud dbaas log-get`

This command downloads a log file from a node.

ibmcloud dbaas log-get RESOURCE_NAME NODE_ID FILE_NAME

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
NODE_ID: The ID of the node.
FILE_NAME: The name of the log file to download. You can use the ibmcloud dbaas logs command to get a list of the existing log files on a node.

`ibmcloud dbaas logs`

This command lists all the log files on a node. You can use any of the listed file names as input to the ibmcloud dbaas log-get command.

ibmcloud dbaas logs RESOURCE_NAME NODE_ID [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
NODE_ID: The ID of the node.
--output: Use the --output option with value json to format output in JSON.

Task commands

`ibmcloud dbaas tasks`

This command lists all the tasks that are running or recently run on a cluster.

ibmcloud dbaas tasks RESOURCE_NAME [--output json]

Command option

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas task`

This command shows details about a task.

ibmcloud dbaas task RESOURCE_NAME TASK_ID [--output json]

Command options

RESOURCE_NAME: The name or CRN of your DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
TASK_ID: The ID of the task.
--output: Use the --output option with value json to format output in JSON.

Backup and restore commands

Use ibmcloud dbaas help backup to see the list of backup and restore commands. backup is the sub namespace that contains all the backup and restore commands.

`ibmcloud dbaas backup enable`

This command enables backups for a database cluster.

ibmcloud dbaas backup enable RESOURCE_NAME --cos-hmac-credentials-path CREDENTIALS_PATH --cos-endpoint COS_ENDPOINT --cos-bucket-crn BUCKET_CRN [--cos-frequency FREQUENCY] [--output json]

Command options

RESOURCE_NAME

The name or CRN of the source DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.

--cos-hmac-credentials-path value

Path to the file that contains the HMAC credentials (access_key_id and secret_access_key) in JSON format. Make sure that you set On for Include HMAC Credential when you create the service credential. You can find the credentials by selecting Service credentials in the IBM Cloud Object Storage web UI. Create a file that contains the complete JSON copied from there or at least what's in the following example. You can also set HMAC credentials as environment variables and omit this command option.

An example of HMAC credentials:

{
    "cos_hmac_keys": {
      "access_key_id": "abc",
      "secret_access_key": "xyz"
    }
}

--cos-endpoint value

Endpoint of IBM Cloud Object Storage (required). In the IBM Cloud Object Storage web UI, select your bucket and you can find Endpoints in the Configuration tab. Only public endpoints are supported for now. Support for private endpoints will come soon.

--cos-bucket-crn value

IBM Cloud Object Storage bucket CRN (required). In the IBM Cloud Object Storage web UI, select your bucket and you can find Bucket instance CRN in the Configurations tab.

--cos-frequency value

The frequency of the backups to IBM Cloud Object Storage. The default value is 8 hours. This option is only available for PostgreSQL. Valid values are 1h, 2h, 4h, 8h, 1d, 2d, and 1w.

--output value

Use the --output option with value json to format output in JSON.

`ibmcloud dbaas backup disable`

This command disables backups for a database cluster.

ibmcloud dbaas backup disable RESOURCE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of the source DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output value: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas backup list`

This command lists the local (not IBM Cloud Object Storage) backups of a database cluster.

ibmcloud dbaas backup list RESOURCE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of the source DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output value: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas backup restore`

This command restores a backup from local storage or IBM Cloud Object Storage for a database cluster. To restore the backup into a new service instance, create a new service instance first.

Restore from local storage:

Local backups can only be restored into your current service instance.

ibmcloud dbaas backup restore RESOURCE_NAME --local-backup-id LOCAL_BACKUP_ID [--output json]

Restore from IBM Cloud Object Storage:

To restore the backup into a new service instance, create a new service instance first.

ibmcloud dbaas backup restore RESOURCE_NAME --cos-hmac-credentials-path CREDENTIALS_PATH --cos-endpoint COS_ENDPOINT --cos-bucket-crn BUCKET_CRN --cos-backup-file FILE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of the target DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output value: Use the --output option with value json to format output in JSON.

Restore from local storage:

--local-backup-id value: The ID of the local backup to be restored (required). You can use the ibmcloud dbaas backup list command to get the list of local backups.

Restore from IBM Cloud Object Storage:

--cos-hmac-credentials-path value

Path to the file that contains the HMAC credentials (access_key_id and secret_access_key) in JSON format. You can find the credentials by selecting Service credentials in the IBM Cloud Object Storage web UI. Create a file that contains the complete JSON copied from there or at least what's in the following example. You can also set HMAC credentials as environment variables and omit this command option.

An example of HMAC credentials:

{
    "cos_hmac_keys": {
      "access_key_id": "abc",
      "secret_access_key": "xyz"
    }
}

--cos-endpoint value

--cos-bucket-crn value

IBM Cloud Object Storage bucket CRN (required). In the IBM Cloud Object Storage web UI, select your bucket and you can find Bucket instance CRN in the Configurations tab.

--cos-backup-file value

The name of the backup file to be restored (required). The backup file name identifies the date and time yyyy-mm-dd-hhmmssZ (UTC) when the backup was generated. You can get a list of COS backup files in either of the following ways.

Using the UI. In the IBM Cloud Object Storage web UI, select your bucket and you can find the available file names in the Object name column in the Objects tab.
Using the IBM Cloud Object Storage CLI plugin.
1. Install and configure the IBM Cloud Object Storage plugin.
2. List backup files with the ibmcloud cos objects --bucket BUCKET command.

`ibmcloud dbaas backup configuration`

This command shows the backup configuration of a database cluster.

ibmcloud dbaas backup configuration RESOURCE_NAME [--output json]

Command options

RESOURCE_NAME: The name or CRN of the source DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.
--output value: Use the --output option with value json to format output in JSON.

`ibmcloud dbaas backup configure`

This command changes the configuration of backup to IBM Cloud Object Storage for a database cluster.

ibmcloud dbaas backup configure RESOURCE_NAME [--cos-hmac-credentials-path CREDENTIALS_PATH --cos-endpoint COS_ENDPOINT --cos-bucket-crn BUCKET_CRN] [--cos-frequency FREQUENCY] [--output json]

Command options

RESOURCE_NAME

The name or CRN of the source DBaaS service instance. To find the resource name or CRN, use the IBM Cloud command ibmcloud resource service-instances --long.

--cos-hmac-credentials-path value

An example of HMAC credentials:

{
    "cos_hmac_keys": {
      "access_key_id": "abc",
      "secret_access_key": "xyz"
    }
}

--cos-endpoint value

Endpoint of IBM Cloud Object Storage. This parameter is required if --cos-bucket-crn is set. In the IBM Cloud Object Storage web UI, select your bucket and you can find Endpoints in the Configuration tab. Only public endpoints are supported for now. Support for private endpoints will come soon.

--cos-bucket-crn value

IBM Cloud Object Storage bucket CRN. This parameter is required if --cos-endpoint is set. In the IBM Cloud Object Storage web UI, select your bucket and you can find Bucket instance CRN in the Configurations tab.

--cos-frequency value

The frequency of the backups to IBM Cloud Object Storage. This option is only available for PostgreSQL. You can use the ibmcloud dbaas backup configuration command to get the current value. Valid values are 1h, 2h, 4h, 8h, 1d, 2d, and 1w.

--output value

Use the --output option with value json to format output in JSON.