dbbot Upgrade and Rollback

This page describes the recommended way to upgrade a dbbot release package on the control host and the scope currently handled automatically by the built-in dbbotctl CLI.

1. Upgrade principle

Do not rely on the old manual flow:

  1. Back up hosts.ini, common_config.yml, and similar files.
  2. Delete /usr/local/dbbot.
  3. Extract the new package.
  4. Copy the old configuration back.

That approach has four obvious problems:

  • Too many manual steps.
  • Online and offline upgrades follow different procedures.
  • Configuration recovery is easy to miss.
  • New template content in the target release is hard to discover.

The recommended method is to always use /usr/local/dbbot/bin/dbbotctl so download, snapshot, replacement, verification, and rollback share the same workflow.

2. Check version and environment first

/usr/local/dbbot/bin/dbbotctl version
/usr/local/dbbot/bin/dbbotctl doctor

doctor checks:

  • local commands such as tar, python3, and mktemp
  • whether curl or wget is available for online upgrades
  • whether the portable Ansible entry can run
  • free disk space on the control host

3. Online upgrade

Upgrade to the latest official release:

/usr/local/dbbot/bin/dbbotctl release upgrade --latest

Upgrade to a fixed tag:

/usr/local/dbbot/bin/dbbotctl release upgrade --tag v0.2.0

Default behavior:

  1. Download the release package.
  2. Validate the package structure.
  3. Create an upgrade snapshot.
  4. Replace files managed by the release package.
  5. Replay preserved local state.
  6. Run ansible-playbook --version and public entry --syntax-check commands.

To preview the plan without changing files:

/usr/local/dbbot/bin/dbbotctl release upgrade --tag v0.2.0 --dry-run

4. Offline upgrade

If the control host has no internet access, copy the release package to the host first and then run:

/usr/local/dbbot/bin/dbbotctl release upgrade --package /tmp/dbbot-v0.2.0.tar.gz

Online and offline upgrades differ only in where the package comes from. The rest of the workflow is the same.

5. What the current implementation preserves

The current dbbotctl release upgrade preserves and restores these local paths:

  • mysql_ansible/inventory/
  • mysql_ansible/downloads/
  • mysql_ansible/playbooks/common_config.yml
  • mysql_ansible/playbooks/advanced_config.yml
  • mysql_ansible/playbooks/vars/
  • mysql_ansible/playbooks/logs/
  • clickhouse_ansible/inventory/
  • clickhouse_ansible/downloads/
  • clickhouse_ansible/playbooks/vars/
  • clickhouse_ansible/playbooks/logs/
  • monitoring_prometheus_ansible/inventory/
  • monitoring_prometheus_ansible/downloads/
  • monitoring_prometheus_ansible/playbooks/common_config.yml
  • monitoring_prometheus_ansible/playbooks/vars/
  • monitoring_prometheus_ansible/playbooks/logs/

Other release-managed content such as roles/, top-level README, the portable Ansible runtime, bin/dbbotctl, and libexec/ is replaced by the target release.

6. Rollback

Show recorded history:

/usr/local/dbbot/bin/dbbotctl release history

Rollback to the latest upgrade snapshot:

/usr/local/dbbot/bin/dbbotctl release rollback

Rollback to a specific snapshot:

/usr/local/dbbot/bin/dbbotctl release rollback 20260321T235959Z_v0.2.0

Upgrade snapshots are stored in:

/usr/local/dbbot/.dbbotctl/snapshots/

Each snapshot directory includes:

  • root-before-upgrade.tar.gz: full pre-upgrade snapshot
  • metadata.env: version, source, and status metadata
  • packaged-preserved-paths/: target-release templates that would otherwise be overwritten by preserved local files

7. Current implementation boundary

The current command already unifies online and offline upgrades, automatic snapshots, rollback, and post-upgrade validation. It does not yet perform YAML key-level smart merges.

That means:

  • your existing configuration is preserved instead of being lost during package replacement
  • target-release templates for overwritten paths are saved in the snapshot directory for manual comparison
  • MySQL and Monitoring are safer because they already rely on default/* fallbacks
  • ClickHouse variable files should still be reviewed carefully after each upgrade