Upgrade database command

The database upgrade command updates an existing VCDB v5 instance to the version of the SQL scripts bundled with vcdb-tool.

  • Be cautious when using the database upgrade command, as it starts the upgrade process immediately. There is no 'Are you sure?' prompt.

  • 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.

Synopsis

vcdb database upgrade [OPTIONS] COMMAND

Options

The database upgrade command inherits global options from the main vcdb command and script options from its parent database command. Additionally, it provides options for upgrading an existing VCDB instance.

Global options

Option Description Default value

[@<filename>…​]

One or more argument files containing options.

-h, --help

Show a help message and exit.

-V, --version

Print version information and exit.

--config-file=<file>

Load configuration from this file.

-L, --log-level=<level>

Log level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Write log messages to this file.

--quiet

Disable console log messages.

--pid-file=<file>

Create a file containing the process ID.

--plugins=<dir>

Load plugins from this directory.

--use-plugin=<plugin[=true|false]>
[,<plugin[=true|false]>…​]

Enable or disable plugins with a matching fully qualified class name.

true

For more details on the global options and usage hints, see here.

Script options

Option Description Default value

-c, --client=<file>

Path to the database client executable.

Client found in your PATH

--timeout=<seconds>

Time in seconds to wait for the operation to complete.

60

For more details on the script options and usage hints, see here.

Upgrade database options

Option Description Default value

--check-only

Perform upgrade pre-checks only. Upgrade will not be applied.

Database connection options

Option Description Default value

-H, --db-host=<host>

Name of the host on which the VCDB is running.

-P, --db-port=<port>

Port of the VCDB server.

5432

-d, --db-name=<database>

Name of the VCDB database to connect to.

-u, --db-username=<user>

Username to use when connecting to the VCDB.

-p, --db-password
[=<password>]

Password to use when connecting to the VCDB. Leave empty to be prompted.

--db-property=<property=value>
[,<property=value>…​]

Database-specific connection properties.

For more details on the database connection options and usage hints, see here.

Unlike other commands, the --db-schema option is not available for database upgrade.

Usage

Upgrading a VCDB instance

A database upgrade is performed by executing the upgrade command with the connection details of the target VCDB instance. The upgrade process first checks the current version of the VCDB instance. If it is already up to date, or if it cannot be migrated automatically — for example, due to a major version change — the command terminates without making any changes.

If an upgrade path exists, the command applies the SQL migration scripts that come with vcdb-tool to bring the VCDB instance in line with the bundled version.

You can check the VCDB version of the bundled SQL scripts using the scripts-version command.
The upgrade scripts are designed only for updating existing VCDB instances. They cannot be used to upgrade a 3DCityDB instance or migrate it to VC Database.

As described here, the connection details can be supplied using the CLI options listed above, or via alternative methods such as a JSON configuration file or environment variables. The following options are mandatory:

  • --db-name: The target database that contains the VCDB instance to upgrade.

  • --db-username: The owner of the VCDB instance or a user with sufficient privileges to perform the upgrade.

An example for the upgrade command is shown below.

  • Linux

  • Windows CMD

./vcdb database upgrade \
    -H localhost \
    -d citydb \
    -u citydb_user \
    -p mySecret
vcdb database upgrade ^
    -H localhost ^
    -d citydb ^
    -u citydb_user ^
    -p mySecret

When the upgrade command is executed, log messages are printed to the console showing the progress of the operation. The command indicates whether the VCDB instance is already up to date, was successfully upgraded, or cannot be upgraded automatically. On error, the log shows the corresponding message to help identify the cause.

When setting the --log-level to debug, the log also includes the output of the database client executing the SQL scripts.

The upgrade command returns the following exit codes to allow automatic interpretation of the upgrade process:

  • 0: Upgrade successful or no upgrade required.

  • 1: Upgrade failed due to errors or issues.

  • 2: Invalid input for an option or parameter.

  • 10: Automatic upgrade not possible.

Pre-checking the upgrade

The --check-only option runs the upgrade process in check-only mode. It compares the current and target database versions to determine whether an upgrade path exists and prints the result to the console. No actual upgrade is applied, allowing you to safely verify whether an upgrade is required and possible.