added chapter on upgrading a 3DCityDB

Author: clausnagel

docs/3dcitydb/.pages

@@ -9,4 +9,6 @@ nav:
     - Codelist module: codelist-module.md
   - db-scripts.md
   - db-functions.md
+  - db-upgrade.md
+  - docker.md
   - ...

docs/3dcitydb/db-scripts.md

@@ -36,6 +36,7 @@ The following table provides an overview of the available shell scripts and thei
 | `revoke-access`      | Revokes read-only or read-write access to a 3DCityDB instance, which has been granted with `grant-access` |
 | `create-changelog`   | Create the changelog extension for a 3DCityDB instance                                                    |
 | `drop-changelog`     | Remove the changelog extension from a 3DCityDB instance                                                   |
+| `upgrade-db`         | Upgrade an existing 3DCityDB instance to a newer minor or patch version                                   |
 
 The scripts are intended to run in an interactive shell session, prompting the user for necessary information to perform
 their tasks. The `connection-details` script serves a special purpose, as it defines the connection details for your

docs/3dcitydb/db-upgrade.md

@@ -0,0 +1,98 @@
+---
+title: Upgrading a 3DCityDB
+description: Upgrading a 3DCityDB to a new minor or patch version
+tags:
+  - 3dcitydb
+  - upgrade
+  - update
+---
+
+Each 3DCityDB `v5` release comes with upgrade scripts that allow you to update an existing 3DCityDB instance to the latest
+release version. The recommended method for upgrading is to use the `upgrade-db` shell script included in the 3DCityDB
+software package. General information on where to find and how to execute the 3DCityDB shell scripts is
+available [here](db-scripts.md#shell-scripts).
+
+!!! note
+    The upgrade scripts are intended **only** for minor and patch version updates within the same major version.
+
+!!! warning
+    The upgrade may involve schema changes. Because this affects the stored city model data, we **strongly recommend backing
+    up your 3DCityDB instance before upgrading**.
+
+## 3DCityDB upgrade steps
+
+### Step 1: Edit the `connection-details` script
+
+Navigate to the `3dcitydb/postgresql/shell-scripts` directory where you have unzipped the 3DCityDB software package,
+or locate the same folder in the installation directory of `citydb-tool`. Make sure you are using the scripts from the
+latest release version you want to upgrade to. Then, change to the subfolder `unix` or `windows`, depending on your
+operating system. 
+
+In this directory, locate the `connection-details.[sh|bat]` script and open it in a text editor of your choice. Enter the
+connection details for the 3DCityDB instance you wish to upgrade, along with the full path to the `psql`
+executable in this file. See [here](db-scripts.md#shell-scripts) for more details.
+
+### Step 2: Run the `upgrade-db` script
+
+After setting the connection details, execute the `upgrade-db.[sh|bat]` script in the same folder to begin the upgrade
+process. You can either double-click the script or run it from a shell environment. On UNIX/Linux machines, you may
+first need to set the appropriate file permissions to make the script executable.
+
+=== "Linux"
+
+    ```bash
+    chmod u+x upgrade-db.sh
+    ./upgrade-db.sh
+    ```
+
+=== "Windows CMD"
+
+    ```bat
+    upgrade-db.bat
+    ```
+
+You can also specify an alternative `connection-details` file from a different directory:
+
+=== "Linux"
+
+    ```bash
+    ./upgrade-db.sh /path/to/connection-details.sh
+    ```
+
+=== "Windows CMD"
+
+    ```bat
+    upgrade-db.bat C:\path\to\connection-details.bat
+    ```
+
+After launching the script, a welcome message and usage information will appear in the console. The script will then
+prompt you for the database password to connect to the 3DCityDB instance.
+
+!!! warning
+    The upgrade process begins immediately after you enter the password — there is no confirmation or 'Are you sure?' prompt.
+
+### Step 3: Upgrade process
+
+The upgrade script first checks the version of your existing 3DCityDB instance to determine if an automatic upgrade to the
+target version is supported. Minor and patch upgrades within the same major version are generally supported. For major
+version upgrades, special migration steps are usually required. If an automatic upgrade is not possible, the process
+will abort with an error message and will not modify your existing database.
+
+If the version check passes, the script proceeds to apply all necessary changes to bring the database up to date. This
+includes applying upgrades across multiple intermediate versions if needed. You do not need to apply each intermediate
+upgrade manually.
+
+The upgrade process updates the default `citydb` schema, all additional data schemas added by the user, and the `citydb_pkg`
+schema, which contains the predefined database functions and procedures.
+
+During the upgrade process, carefully monitor the log messages printed to the console. Look out for any errors or
+warnings, and take appropriate action if any issues are reported. A successful upgrade will conclude with a
+confirmation message similar to:
+
+```bash
+3DCityDB instance successfully upgraded.
+```
+
+!!! tip
+    After completing the upgrade, it is highly recommended to run a `VACUUM` on the affected database tables to ensure optimal
+    performance.

docs/first-steps/setup.md

@@ -218,4 +218,9 @@ ALTER DATABASE new_citydb_v5 SET search_path TO citydb, citydb_pkg, public;
 
 !!! info
     If your 3DCityDB template contains more schemas, ensure to add them all to the `search_path`.
-    Note that the search path will be updated upon the next login, not within the same session.
+    Note that the search path will be updated upon the next login, not within the same session.
+
+## Upgrading a 3DCityDB `v5` to the latest release
+
+If you already have a 3DCityDB `v5` installed and running, and want to update it to the latest release instead of
+setting up a new instance, please follow this [guide](../3dcitydb/db-upgrade.md).