Full Restart Upgrade

The preferred method for upgrading a CrateDB cluster is the Rolling Upgrade process, which allows for zero-downtime upgrades.

However, a full restart upgrade is necessary in certain cases, such as:

• When upgrading across non-consecutive feature versions (e.g., from X.5.x directly to X.8.x)

• When explicitly required by the release notes

• When using testing or development builds that don’t support rolling upgrades

Caution: These instructions apply to most installation methods. If you are using Docker, be aware that docker service update performs a rolling upgrade by default. To perform a full restart upgrade in Docker, you must remove the service and recreate it with the new image.

Before You Begin

Warning: Before upgrading, you must back up your data using CrateDB’s snapshot mechanism.

You should also:

• Notify relevant stakeholders about the expected downtime

• Plan a maintenance window

• Validate your upgrade plan in a test environment, if possible

---

Full Restart Upgrade Steps

Step 1: Stop All Nodes

Shut down the CrateDB process on every node in the cluster using the appropriate method for your setup:

• Systemd:

  sudo systemctl stop crate

• Tarball: If CrateDB was started manually:

  Ctrl+C or kill <PID>

• Docker:

  docker service rm crate  # For full restart upgrade

Ensure every node is stopped before proceeding. Continuing the upgrade with nodes still running can lead to data corruption or data loss.

---

Step 2: Upgrade CrateDB on All Nodes

Upgrade the CrateDB binary or package on each node using the method appropriate to your environment:

• RPM-based systems (RHEL, CentOS, etc.):

  sudo yum update -y crate

• Debian-based systems (Ubuntu, etc.):

  sudo apt-get update
  sudo apt-get install --only-upgrade crate

• Tarball: Replace the existing CrateDB directory with the new version:

  tar -xzf crate-<new-version>.tar.gz

• Docker: Pull the new image and recreate the service:

  docker pull crate/crate:<new-version>
  docker service create --name crate crate/crate:<new-version>

Refer to your OS or orchestration platform’s documentation for specific upgrade instructions.

---

Step 3: Restart All Nodes

Once all nodes have been upgraded:

• Restart each node, using the method appropriate for your installation.

Examples:

• Systemd:

  sudo systemctl start crate

• Tarball:

  /path/to/crate/bin/crate

• Docker: See your orchestration documentation (e.g., docker service create, docker-compose up)

The cluster will automatically recover and re-form once all upgraded nodes are online.

---

After the Upgrade

• Check cluster health and logs to verify everything is functioning properly:

  SELECT * FROM sys.health;

• Run sample queries or smoke tests to confirm that data is accessible and operations work as expected

• Re-enable any maintenance configurations you may have disabled (e.g., shard allocation)

---

Summary

Step	Action
1. Stop Nodes	Gracefully shut down all nodes
2. Upgrade Software	Install the new CrateDB version on each node
3. Start Nodes	Restart the CrateDB service on all nodes