diff --git a/mintlify/content/docs/administration/back-up-data/change-migration-history.webp b/mintlify/content/docs/administration/back-up-data/change-migration-history.webp deleted file mode 100644 index 1a363d36b..000000000 Binary files a/mintlify/content/docs/administration/back-up-data/change-migration-history.webp and /dev/null differ diff --git a/mintlify/get-started/self-host/production-setup.mdx b/mintlify/get-started/self-host/production-setup.mdx index c1b9f9017..fbcc9104a 100644 --- a/mintlify/get-started/self-host/production-setup.mdx +++ b/mintlify/get-started/self-host/production-setup.mdx @@ -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 diff --git a/mintlify/get-started/self-host/upgrade.mdx b/mintlify/get-started/self-host/upgrade.mdx index 798fbb206..bdadc2de9 100644 --- a/mintlify/get-started/self-host/upgrade.mdx +++ b/mintlify/get-started/self-host/upgrade.mdx @@ -73,18 +73,8 @@ psql -h <> -p <> -U <> 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`: @@ -98,7 +88,7 @@ Restore metadata to the new db: psql -h <> -p <> -U <> 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: @@ -147,91 +137,3 @@ Take Docker as an example (**follow the below steps exactly**): -## 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 - - - Downgrade is as dangerous as upgrade, we highly recommend you verify the downgrade in a test - environment first. - - -### 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