Upgrading a VCDB

Each VC Database v5 release comes with upgrade scripts that allow you to update an existing VCDB instance to the latest release version. The recommended method for upgrading is to use the upgrade-db shell script included in the VCDB software package. General information on where to find and how to execute the VCDB shell scripts is available here.

  • The upgrade scripts are intended only for minor and patch version updates within the same major version.

  • The upgrade may involve schema changes. Because these changes affect the stored city model data, we strongly recommend backing up your VCDB instance before upgrading.
The upgrade scripts are designed only for updating existing VCDB instances. They cannot be used to migrate a 3DCityDB instance to VC Database.

VCDB upgrade steps

Step 1: Edit the connection-details script

Navigate to the vcdb/postgresql/shell-scripts directory where you have unzipped the VCDB software package, or locate the same folder in the installation directory of VCDB-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 VCDB instance you wish to upgrade, along with the full path to the psql executable in this file. See here 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

  • Windows CMD

chmod u+x upgrade-db.sh
./upgrade-db.sh
upgrade-db.bat

You can also specify an alternative connection-details file from a different directory:

  • Linux

  • Windows CMD

./upgrade-db.sh /path/to/connection-details.sh
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 VCDB instance.

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 VCDB 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 both the citydb_pkg and vcdb_pkg schemas, which contain 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:

VC Database instance successfully upgraded.
After completing the upgrade, it is highly recommended to run a VACUUM on the affected database tables to ensure optimal performance.