​
Upgrade Process

This guide walks through upgrading Bytebase with Docker. Complete each step sequentially to ensure a smooth and safe upgrade:

​
Step 1: Stop and Remove the Existing Container

First, gracefully stop and remove your current Bytebase container. This prevents data corruption by ensuring no concurrent access to the metadata.

​
Step 2: Back Up Your Metadata

🚨 Critical: Before proceeding, create a complete backup of your metadata. This backup serves as your safety net for rolling back if needed. Refer to the “Back up and Restore” section below for comprehensive backup procedures.

​
Step 3: Launch the Updated Version

Start Bytebase with the new version using your existing Docker run command, updating only the image tag to the desired version.
Production Safety: Validate your upgrade procedure in a staging environment before executing it in production.

​
Back up and Restore (External PostgreSQL)

​
Creating a Backup

Execute the following command to create a complete database clone: 
CREATE DATABASE metadb_backup WITH TEMPLATE metadb;

​
Restoring from Backup

  1. Stop your Bytebase instance completely.
  2. Preserve the current database by renaming it: 
    ALTER DATABASE metadb RENAME TO metadb_old;
  3. Restore from your backup: 
    CREATE DATABASE metadb WITH TEMPLATE metadb_backup;
  4. Start Bytebase with the previous version (the version you were running before the failed upgrade).
  5. After confirming successful restoration, remove temporary databases: 
    DROP DATABASE metadb_old;
DROP DATABASE metadb_backup;