From 35cb0681cf0ac8c27efaacc7c41274a837cc098a Mon Sep 17 00:00:00 2001 From: Akira KAWAGUCHI Date: Tue, 5 Dec 2023 20:24:54 +0900 Subject: [PATCH] doc: add upgrade guide document --- docs/upgrade-guide.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/upgrade-guide.md diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md new file mode 100644 index 0000000..0d417d7 --- /dev/null +++ b/docs/upgrade-guide.md @@ -0,0 +1,41 @@ +# Tsurugi Upgrade Guide + +This is a generic guide for upgrading across versions of Tsurugi. + +## Upgrading instructions + +### 1. Stop old version of Tsurugi clients and server + +- Stop tsurugi client applications and client tools (ex. Tsurugi SQL Console). +- Stop Tsurugi Server (tsurugidb process) by run `tgctl shutdown`. + +### 2. Install a new version of Tsurugi server + +- Install the new version of Tsurugi by following document. + - [Tsurugi Getting Started - Installation Instructions](https://github.com/project-tsurugi/tsurugidb/blob/master/docs/getting-started.md#installation-instructions) + - The installer places Tsurugi into different directories for each version, so that previous versions will never be changed. + - If `--symbolic` option is specified and a symbolic link for the old version already exists in that location, it will be changed to link to the new version. + +### 3. Update version of client library + +- Updating the server version may break the message compatibility between the server and the client library (Tsubakuro). +- Please refer to the following document and update Tsubakuro used by client applications if necessary. + - [Service Message Version (SMV) Compatibility](https://github.com/project-tsurugi/tsurugidb/blob/master/docs/service-message-compatibilities.md) + +### 4. Migrate configuration file of Tsurugi server + +- Apply the configuration items (changed from the default settings) in the old version of the configuration file ( `var/etc/tsurugi.ini` ) to the new version of that. +- It is NOT RECOMMENDED to directly substitute the old configuration file with the new one. + - Newer versions of the configuration file may have new items, or the default settings may have changed. + +### 5. Migrate transaction log files of Tsurugi server + +- Copy the old version of the transaction log data directory ( `var/data` ) to the new version of that. +- Log data migration possibly requires additional procedures. Please check the release notes. + - In such the cases, the database will fail on startup because the restore operation cannot be performed correctly. + +### 6. Start new version of Tsurugi server and clients + +- Start Tsurugi Server (tsurugidb process) by run `tgctl start`. +- Start tsurugi client applications or client tools (ex. Tsurugi SQL Console) +- Check client applications execution and migrated data.