Upgrade

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

The procedure depends on where Bytebase stores its metadata:

• Embedded PostgreSQL — the default. You did not set PG_URL, and the metadata lives in the data directory mounted into the container. Back up that directory.
• External PostgreSQL — you set PG_URL, and the metadata lives in the database named in that connection string. Clone that database.

Embedded PostgreSQL

The embedded PostgreSQL listens only on a Unix socket inside the container and shuts down together with Bytebase, so it cannot be cloned from another host. Back up the mounted data directory instead.

The examples below assume the docker run command from Deploy with Docker, which mounts ~/.bytebase/data at /var/opt/bytebase. Substitute your own host path.

Back Up the Data Directory

1. Stop Bytebase so PostgreSQL shuts down cleanly:

   docker stop bytebase
   

   Add docker rm bytebase if you did not start the container with --rm.

2. Copy the host directory somewhere safe. An archive travels well:

   sudo tar czf ~/bytebase-backup-$(date +%Y%m%d).tar.gz -C ~/.bytebase/data .
   

   A plain directory copy is equally valid for a local rollback, as long as it preserves ownership and permissions:

   sudo cp -a ~/.bytebase/data ~/bytebase-backup
   

Copy the directory only while Bytebase is stopped. A copy taken from a running instance captures PostgreSQL mid-write and may not restore.

Restore the Data Directory

1. Stop your Bytebase instance completely.

2. Move the current data directory aside rather than deleting it, then put the backup in its place:

   sudo mv ~/.bytebase/data ~/.bytebase/data.old
   sudo mkdir -p ~/.bytebase/data
   sudo tar xzf ~/bytebase-backup-<date>.tar.gz -C ~/.bytebase/data
   

   From a directory copy instead:

   sudo cp -a ~/bytebase-backup/. ~/.bytebase/data
   

3. Start Bytebase with the previous version (the version you were running before the failed upgrade).

4. After confirming successful restoration, remove ~/.bytebase/data.old.

Restore as root, and with a command that preserves ownership — tar as root and cp -a both do, a plain cp -r does not. Bytebase repairs the permissions of the data directory itself, but not the ownership of the files inside it, and PostgreSQL refuses to start when it does not own them.

External PostgreSQL

Replace <dbname> in the statements below with the database named in your PG_URL — the same value you supplied when you configured External PostgreSQL. To check which one you are using:

psql "$PG_URL" -c 'SELECT current_database();'

Back Up the Metadata Database

Connect to another database on the same PostgreSQL server — postgres always exists — and clone the metadata database:

CREATE DATABASE <dbname>_backup WITH TEMPLATE <dbname>;

WITH TEMPLATE requires that no other session is connected to the source database. Stop Bytebase first, or PostgreSQL fails with source database ... is being accessed by other users.

Restore the Metadata Database

1. Stop your Bytebase instance completely.

2. Preserve the current database by renaming it:

   ALTER DATABASE <dbname> RENAME TO <dbname>_old;
   

3. Restore from your backup:

   CREATE DATABASE <dbname> WITH TEMPLATE <dbname>_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 <dbname>_old;
   DROP DATABASE <dbname>_backup;