Upgrading a Database

      Upgrades are scheduled as needed on databases to provide a reliable service with the latest features.

      This page walks you through support, timeframes, and maintenance jobs for database upgrades in Couchbase Capella. Use the procedures on this page to view and reschedule upgrade maintenance jobs for your databases.

      Couchbase Server Version Support

      Capella schedules upgrade maintenance jobs for the following types of Couchbase Server releases:

      Release Introduces


      Major new features and functionality.


      Some new features or improvements.

      Maintenance or Patch

      Essential fixes and improvements.

      By carefully managing the upgrade process, Capella tries to make upgrading as easy as possible. For maintenance and patch releases, you can expect none to minimal impact.

      When an upgrade maintenance job is scheduled, you can choose to upgrade your database at any time before the scheduled date. Depending on the type of upgrade and the target start time, you can schedule a new date. This is a new target start time. When the scheduled time is reached, the database is automatically upgraded.

      The notice that Capella aims to provide varies depending on the nature of the upgrade. For example, major version upgrades often require application testing. The upgrade window for major versions is longer than for maintenance, patch, and minor version upgrades. See Database Upgrade Timeframes.

      In addition to Couchbase Server upgrades, Capella may schedule routine upgrade maintenance jobs that do not upgrade the Couchbase Server version, but apply essential updates to the systems your database runs on.

      Database Upgrade Timeframes

      When a maintenance job is scheduled, email notifications are sent. See Maintenance Jobs. The initial scheduling and creation of the upgrade maintenance job starts the notice period. This is the time between notification and the target start time for the upgrade.

      A critical upgrade may have 0 days notice period, and the upgrades are scheduled immediately. A more typical notice period is 2 weeks. If the notice period is 2 weeks, you can see that the target start time for your database upgrade is set to at least 2 weeks out from the notification date.

      Below are additional details about the different types of upgrade maintenance jobs and the time frames to complete the upgrade.

      Upgrade or Maintenance Type Description

      Critical Upgrade

      An upgrade done in response to an urgent bug, vulnerability, or other issue impacting database health or performance.

      Upgrades can be scheduled on the same date as maintenance job creation and same date as upgrade maintenance notification. Therefore, you may have 0 days notice of a pending upgrade maintenance job before the database is automatically upgraded.

      Routine Maintenance or Couchbase Server Patch

      A new Couchbase Server maintenance, patch version, or routine image upgrades.

      A typical upgrade maintenance job window includes a 2 weeks notice period. The time between the scheduled upgrade date (target start time) and when the upgrade maintenance job is created (maintenance notifications are sent) is at least 2 weeks. You can reschedule the upgrade up to the end target date. This is the latest possible upgrade schedule date specified in the upgrade maintenance job. The end target date is typically 4 weeks from the end of the notice period.

      In the Capella UI, when you click on the upgrade maintenance job name, you can see the full details of the upgrade, including what’s in the new version. You can also see options that allow you to change when the upgrade maintenance job runs. See Maintenance Jobs.

      Couchbase Server Minor Release

      A new Couchbase Server minor version release.

      Upgrade time frames are variable based on actual features and improvements included in the minor version release and how they may impact Capella users. If the service impact is similar to a Server maintenance or patch release, the typical notice and upgrade maintenance job dates as used with Server maintenance or patch releases is applied.

      Couchbase Server Major Release

      A new Couchbase Server major release version.

      Upgrade time frames are variable. Since major version upgrades often require application testing, the upgrade window for major versions is longer than for maintenance and minor version upgrades. When the upgrade window is announced for a major version upgrade, a suitable notice period is given to allow application testing.

      Maintenance Jobs

      All maintenance jobs have a target start time. Capella aims to start the maintenance of your database at this time. However, maintenance jobs are sometimes delayed when a database cannot be upgraded. For example, when a database is reconfiguring.

      Database maintenance screen
      Figure 1. Database maintenance screen

      Maintenance job statuses are pending, running, and completed.

      For each individual maintenance job, you can:

      • View its type, status, and scheduled time to upgrade.

      • Review its overview and what’s new.

      • Reschedule it to upgrade at a different time.

      • Create a support ticket.

      When a maintenance job is scheduled, email notifications are sent to:

      • Organization Owners where one or more databases in their organization is scheduled for maintenance.

      • Project Owners and Project managers where at least one database on a project they have access to is scheduled for maintenance.

      You can review all scheduled maintenance jobs that have run on the database. For more information, see Activity Log.

      You can reschedule the target start time for an individual maintenance job or choose to run the maintenance job immediately. However, maintenance jobs cannot be deferred indefinitely because each maintenance job has a latest possible upgrade date.

      When a maintenance job runs, the database is moved to a redeploying state while nodes are rebalanced to apply the maintenance changes. Maintenance redeployments are not time-bound, and the time taken varies depending on the size of the database, volume of data, and load. Couchbase Capella databases are designed to remain available throughout the upgrade. Database reconfiguration options are not available during an upgrade, though data tools remain accessible in the Capella UI.

      View Individual Maintenance Jobs

      You can view scheduled maintenance upgrade jobs for your databases:

      1. On the Databases page, find and click the name of the database you’re working with.

      2. Click the Settings tab.

      3. In the navigation pane, click Maintenance.

      Reschedule an Individual Maintenance Job

      You can reschedule an individual maintenance job. You can create a support ticket to ask for an extension if there are exceptional circumstances. Extensions are not guaranteed.

      Database reschedule job
      Figure 2. Database reschedule job

      To reschedule:

      1. On the database’s Maintenance page, click on the job name in the Maintenance Jobs list.

      2. Select one of the following:

        • Keep current schedule.

        • Change time.

          Click the date picker and set the preferred date and start time.

        • Run now.

      3. Click Save.

      Set a Preferred Time for all Maintenance Jobs

      You can set a preferred time and day of the week for future maintenance jobs to be scheduled. This does not reschedule maintenance jobs that are already scheduled on the Maintenance tab.

      When an upgrade or maintenance becomes available, Capella attempts to schedule the maintenance at your preferred time and day of the week. The preferred time is not a guarantee. If it is not possible to schedule the maintenance at your preferred time, the database is scheduled at any time within the maintenance window.

      To set a preferred maintenance day and time for all upcoming jobs:

      1. On the Databases page, find and click the name of the database you’re working with.

      2. Click the Settings tab.

      3. In the navigation pane, click Maintenance.

      4. Click Set Time.

      5. Select Enable a preferred start time for database maintenance.

      6. In the Day of the Week list, select the day you want scheduled maintenance to occur.

      7. In the Time field, enter the time you want scheduled maintenance to occur.

        This time is local to you, and you enter it using the HH:mm format. For example: 14:30.

      8. Click on Save.

      See Also

      See the following pages for more information about managing databases: