Upgrading in the UI

1. Create a new Databases for MongoDB to test the upgrade process.
   Create the deployment by restoring a backup from your existing deployment with the same version.

2. Point your staging application to the test deployment.
   Update your staging application to point to the test deployment. Confirm that your test application can connect successfully to the staging deployment and that the application operates as expected. Perform any required performance and operational testing of the staging environment.

3. Upgrade the major version of your test deployment by clicking on the Upgrade major version button on the Overview page.
   This will put your database into READ-ONLY mode while the upgrade process completes. Note how long the upgrade takes to complete so that you can use the upgrade expiry setting to contain upgrades within your maintenance window.

4. Confirm that your staging application works with the new database version.
   If your application works, this step confirms that it should be safe to upgrade your production database.

5. Upgrade your production database deployment to the new version.
   Once you confirmed that your application works correctly by using the new version of the database, you can return to the management console and start the process of upgrading your production deployment. In the Deployment details section of the Overview page, click the Upgrade major version button and follow the steps.

   Once the in-place upgrade process starts, it cannot be stopped or rolled back. So, in the unlikely event of an error, your database deployment could become unrecoverable. Therefore, create a backup that you can then use to restore to a new deployment. If you select 'In-place major version upgrade with backup', the backup that is created can be used to restore in a new deployment.

The expiration for starting upgrade allows you to configure a 'timeout' period that the upgrade job must start within before it is automatically cancelled. In addition, test the upgrade in staging upfront to ensure that the upgrade completes within your desired time window. If, for example, you want to complete the upgrade within 1 hour, and you tested the upgrade and know that it takes 30 minutes, then your upgrade job must start within 30 minutes of you confirming that you want to upgrade. Therefore, set the expiration to 30 minutes, so that if it doesn't start within that time, it won't overrun your window.

Upgrading through the API

Use the following command to upgrade in-place:

curl -X PATCH https://api.{region}.databases.cloud.ibm.com/v5/ibm/deployments/{id}/version -H 'Authorization: Bearer <>' -H 'Content-Type: application/json' -d '{"version": "7.0"}'

The expiration for starting upgrade allows you to configure a 'timeout' period that the upgrade job must start within before it is automatically cancelled. In addition, test the upgrade in staging upfront to ensure that the upgrade completes within your desired time window. If, for example, you want to complete the upgrade within 1 hour, and you tested the upgrade and know that it takes 30 minutes, then your upgrade job must start within 30 minutes of you confirming that you want to upgrade. Therefore, set the expiration to a timestamp of 30 minutes from now, so that if it doesn't start within that time, it won't overrun your window. The expiration must be between 5 minutes (default) and 24 hours from now. For more information, see the Cloud Databases API.

Upgrading through the CLI

Available in CDB plugin version >= 0.20.0

To view the list of allowed upgrade and restore transitions for the deployment:

ibmcloud cdb deployment-capability-show <NAME|CRN> versions

To upgrade command with required parameters:

ibmcloud cdb deployment-version-upgrade <NAME|CRN> <TARGET_VERSION>

To view full details of command parameters:

ibmcloud cdb deployment-version-upgrade --help

The expiration for starting upgrade allows you to configure a 'timeout' period that the upgrade job must start within before it is automatically cancelled. In addition, test the upgrade in staging upfront to ensure that the upgrade completes within your desired time window. If, for example, you want to complete the upgrade within 1 hour, and you tested the upgrade and know that it takes 30 minutes, then your upgrade job must start within 30 minutes of you confirming that you want to upgrade. Therefore, set the expiration to 30 minutes, so that if it doesn't start within that time, it won't overrun your window. The expiration must be between 5 mins (default) and 24 hours from now. There are two ways to set expiration using CLI --expire-in or --expire-at. For more information refer to the command help.

Upgrading through Terraform

Available in Terraform provider version >= 1.79.2

To upgrade, just add or change the version value in your configuration. There is also an optional bool flag, version_upgrade_skip_backup, that you can set to skip backup.

Skipping a backup is not recommended. Skipping a backup before a version upgrade is dangerous and may result in data loss if the upgrade fails at any stage — there will be no immediate backup to restore from.

The database will be put into READ-ONLY mode during upgrade. It is highly recommended to test before upgrading.

Upgrading may require more time than the default timeout. A longer timeout value can be set with using the timeouts attribute.

Terraform has timeouts instead of expiration timestamps. Therefore, increase your timeout, as your timeout update value is used as the expiration. For example, if you set a timeout of 20 minutes, the expiration will be set to 20 minutes and if the upgrade does not start in that time frame, it expires and the upgrade will not start. Note that the maximum expiration is 24 hours — so even if you set a timeout of 36 hours, the upgrade will expire if it hasn't started within the first 24 hours.

If an upgrade is in progress, note that some tasks may be queued and will not proceed until the version upgrade completes.

Upgrading in the UI

For new hosting models (isolated compute and shared compute), upgrading to a new major version is available through the CLI and API.

You can upgrade to a new version by restoring a backup from the Backups and restore page of your deployment on the IBM Cloud console. Click Restore backup on a backup to open a page in a new tab where you can change some options for the new deployment. One of them is the database version, which is auto-populated with the versions available for you to upgrade to. Select a version and click Restore backup to start the provision and restore process.

Upgrading through the CLI

When you upgrade and restore from backup through the IBM Cloud CLI, use the provisioning command from the resource controller.

ibmcloud resource service-instance-create <INSTANCE_NAME> <SERVICE_ID> <SERVICE_PLAN_ID> <REGION>

The parameters instance_name, service_id, service_plan_id, and region are all required. You also supply the -p with the version and backup ID parameters in a JSON object. The new deployment is automatically sized with the same disk and memory as the source deployment at the time of the backup.

ibmcloud resource service-instance-create example-upgrade databases-for-mongodb standard us-south \
-p \ '{
  "backup_id": "crn:v1:bluemix:public:databases-for-mongodb:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
  "version":"7.0"
}'

Upgrading through the API

Similar to provisioning through the API, you must complete the necessary steps to use the resource controller API before you can use it to upgrade from a backup. Then, send the API a POST request. The parameters name, target, resource_group, and resource_plan_id are all required. Also supply the version and backup ID. The new deployment has the same memory and disk allocation as the source deployment at the time of the backup.

curl -X POST   https://resource-controller.cloud.ibm.com/v2/resource_instances   -H 'Authorization: Bearer <>'   -H 'Content-Type: application/json'     -d '{
    "name": "my-instance",
    "target": "us-south",
    "resource_group": "5g9f447903254bb58972a2f3f5a4c711",
    "resource_plan_id": "databases-for-mongodb-standard",
    "backup_id": "crn:v1:bluemix:public:databases-for-mongodb:us-south:a/54e8ffe85dcedf470db5b5ee6ac4a8d8:1b8f53db-fc2d-4e24-8470-f82b15c71717:backup:06392e97-df90-46d8-98e8-cb67e9e0a8e6",
    "version":"7.0"
  }'

Upgrading through Terraform

Use Terraform to restore to a backup from an older version to a new version.

1. Set your backup_id. For more information, see backup_id.
2. Set your version in the version attribute. For more information, see version.

The code looks like as follows:

resource "ibm_database" "<your-instance>" {
  name                                 = "<your_database_name>"
  service                              = "<service>"
  plan                                 = "<plan>"
  location                             = "<region>"
  version                              = "<version>"
  backup_id                            = "<backup_id>"
}

For more information, see the Cloud Databases Terraform Registry.