​

Upgrade Process

Take Docker as an example:

1. Stop Bytebase

   Copy

   Ask AI

   docker stop bytebase
   docker rm bytebase
   

2. 🚨 Back up the Bytebase metadata

   Copy

   Ask AI

   cp -rp ~/.bytebase/data ~/.bytebase/data.bak
   

   Above example backs up the metadata stored in the embedded database. If you store metadata in the external PostgreSQL, you should back up that database.

3. Change version string to 3.8.0

4. Start Bytebase

   Copy

   Ask AI

   docker run --rm --init \
     --name bytebase \
     --publish 8080:8080 --pull always \
     --volume ~/.bytebase/data:/var/opt/bytebase \
     bytebase/bytebase:3.8.0
   

​

Version Management

Bytebase adopts Semantic Versioning using the MAJOR.MINOR.PATCH format.

Bytebase ties the version number with the underlying database schema progression, because:

1. Schema change is a good approximate to the functional change. Large schema changes often indicate large functional changes.

2. Schema change determines the customer involvement when upgrading to the new version.

   • MAJOR version change usually happens once a year. It might require manual effort from the customer. Bytebase will try to avoid that if possible.
   • MINOR version is changed when the underlying database schema changes. While the upgrade does not require customer involvement. MINOR version change usually happens about once every month.
   • PATCH version is changed when the new version does not include underlying database schema changes. PATCH version change usually happens bi-weekly following our release schedule.

​

Docker Image Version

Certain changes maybe cherry-picked into the existing version. So when Bytebase starts next time, it will self-upgrade. If you don’t want this behavior, you could use the image digest to pin the exact commit. For example,

# https://hub.docker.com/repository/docker/bytebase/bytebase/tags/3.7.0/sha256-29be3c651d4fc93c6aab37046b41128015a9be5d6f02b2490353962c469c5110
docker pull bytebase/bytebase:3.7.0@sha256:00b436855b08739aad02fd52e41b5d74c03db9c70c49ce5de42376347cd1403c

The docker image is built with OpenContainers Annotations:

docker inspect bytebase/bytebase:3.7.0 | jq -r '.[0].Config.Labels'
{
  "org.opencontainers.image.revision": "fb430b0626c33d3431e750dc0cc446f3c8a434a8",
  "org.opencontainers.image.version": "3.7.0"
}

# Digest also works
docker inspect bytebase/bytebase:3.7.0@sha256:00b436855b08739aad02fd52e41b5d74c03db9c70c49ce5de42376347cd1403c | jq -r '.[0].Config.Labels'
{
  "org.opencontainers.image.revision": "ec5d81d554287258095377c076528d8ab6664fa0",
  "org.opencontainers.image.version": "3.7.0"
}

• org.opencontainers.image.revision is the git commit hash, in the example, it corresponds to the particular git commit
• org.opencontainers.image.version is the release version, in the example, it corresponds to the 3.7.0 release branch.

If you want to check the commit history for the image, the best way is to visit the release branch page and locate the commit:

​

Upgrade from Old Version

​

Upgrade from 3.3.1

Just replace the version string and restart. Bytebase will self-upgrade automatically.

​

Upgrade from 3.0.0 ~ 3.3.0

First upgrade to 3.3.1 and then upgrade to the latest version.

​

Upgrade from 1.x or 2.x

Please first upgrade to 2.1.0 and then upgrade to the latest version.