Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file not shown.
9 changes: 8 additions & 1 deletion mintlify/get-started/self-host/production-setup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,13 +26,20 @@ Teams that frequently work with large SQL files may need more.

## Production Setup Checklist

### Prerequisites
### Essential Configuration

- Review system requirements (see above)
- [Configure External PostgreSQL](/get-started/self-host/external-postgres/)
- [Configure External Access](/get-started/self-host/external-access)
- [Configure External URL](/get-started/self-host/external-url)
- Pin Docker image to specific version instead of `latest` ([changelog](https://docs.bytebase.com/changelog))

While version tags like `3.7.0` are better than `latest`, Bytebase may still add patches to existing versions. For a truly fixed version, use the SHA256 digest from [Docker Hub](https://hub.docker.com/r/bytebase/bytebase/tags).

```bash
# Pin to exact image using digest (prevents any updates)
docker pull bytebase/bytebase:3.7.0@sha256:00b436855b08739aad02fd52e41b5d74c03db9c70c49ce5de42376347cd1403c
```

### Monitoring

Expand Down
102 changes: 2 additions & 100 deletions mintlify/get-started/self-host/upgrade.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -73,18 +73,8 @@ psql -h <<host>> -p <<port>> -U <<user>> postgres -c "DROP DATABASE metadb_old"

#### Restore Option 2 - Restore to a different database `metadb2`

##### Step 1 - Modify the dump file

The dump file records the Bytebase metadata schema change history, and it's database specific. So we
need to change the existing record value from `metadb` to `metadb2` first, which means to transfer
the change history to `metadb2`.

Locate the `migration_history` table in the dump file, and for each record, find the value `metadb`
which corresponds to the `namespace` column, change each occurrence from `metadb` to `metadb2`.

![change-migration-history](/content/docs/administration/back-up-data/change-migration-history.webp)

##### Step 2 - Restore metadata to `metadb2`
##### Step 1 - Restore metadata to `metadb2`

Create a new db `metadb2`:

Expand All @@ -98,7 +88,7 @@ Restore metadata to the new db:
psql -h <<host>> -p <<port>> -U <<user>> metadb2 < metadb.sql
```

##### Step 3 - Drop the old metadata db
##### Step 2 - Drop the old metadata db

Restart Bytebase and verify the metadata is restored properly. Afterwards, you can drop the old database:

Expand Down Expand Up @@ -147,91 +137,3 @@ Take Docker as an example (**follow the below steps exactly**):

<TerminalDockerRunVolume />

## Version Management

Bytebase adopts [Semantic Versioning](https://semver.org/) 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.
1. 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,

```bash
# 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](https://specs.opencontainers.org/image-spec/annotations/):

```bash
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](https://github.com/bytebase/bytebase/commit/fb430b0626c33d3431e750dc0cc446f3c8a434a8)
- `org.opencontainers.image.version` is the release version, in the example, it corresponds to the [3.7.0 release branch](https://github.com/bytebase/bytebase/commits/release/3.7.0).

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:

![release-commit](/content/docs/get-started/upgrade/release-commit.webp)

## Upgrade from Old Version

To upgrade, replace the version string with the target version and restart. Bytebase will self-upgrade automatically.

### Upgrade from 1.x or 2.x

First upgrade to 2.1.0 and then follow the next section.

### Upgrade from 3.0.0 ~ 3.3.0

First upgrade to 3.3.1 and then follow the next section.

### Upgrade from 3.3.1

Replace the version string with the latest version and restart.

## Downgrade

<Warning>
Downgrade is as dangerous as upgrade, we highly recommend you verify the downgrade in a test
environment first.
</Warning>

### Downgrade PATCH Version

Downgrades carry the same risks as upgrades, so validate any downgrade in a test environment before proceeding.

### Downgrade MINOR Version

Minor version upgrade/downgrade involves metadata schema change, so we must restore the metadata database to the old version first.
Thus the metadata backup for the old version must be available.

1. Stop Bytebase
1. Restore the metadata database with the metadata backup
1. Replace the version with the old version.
1. Start Bytebase

### Downgrade MAJOR Version

Not supported