Database Command

The database command lets you create, upgrade, or drop a VC Database v5 instance. Each action is provided as dedicated subcommand, which runs the corresponding VCDB SQL scripts to perform the operation. The subcommands offer a convenient alternative to executing the SQL scripts directly or via the bundled shell scripts, and make it easy to integrate the database management operations into automation workflows.

In addition, the scripts-version subcommand is available to print the version number of the bundled SQL scripts.

Synopsis

vcdb database [OPTIONS] COMMAND

Options

The database command inherits global options from the main vcdb command. Additionally, it defines script options, which apply to all of its subcommands that run SQL scripts.

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

The script options are available for all subcommands that run SQL scripts. They do not apply to the scripts-version subcommand.

Commands

Command Description

help

Display help information about the specified command.

create

Create a new VC Database instance.

upgrade

Upgrade an existing VC Database instance.

drop

Drop an existing VC Database instance.

scripts-version

Show version of the bundled VC Database SQL scripts.

Usage

Specifying script options

The create, upgrade, and drop subcommands run the VCDB SQL scripts bundled in the vcdb-sql folder within the vcdb-tool installation directory to perform the corresponding database operation. The SQL scripts are executed in the background by the database-specific command-line client. Therefore, the required database client — specifically psql for PostgreSQL — must be installed and available on your system before running these commands.

The --client option allows you to provide the full path to the client executable. If not provided, the client executable is searched for in the user or system PATH by default.

When using the official Docker image for vcdb-tool, all supported database clients come preinstalled in the container. In this scenario, the --client option can be safely skipped.

The --timeout option lets you specify the maximum number of seconds to wait for the database client to complete execution of the SQL scripts. If this time is exceeded, the command will forcibly terminate the database client and exit with an error. The default wait time is 60 seconds.

  • Linux

  • Windows CMD

./vcdb database create [...] \
    --client /usr/bin/psql \
    --timeout 120
vcdb database create [...] ^
    --client "C:\Program Files\PostgreSQL\18\bin\psql.exe" ^
    --timeout 120

Checking SQL scripts version

The scripts-version subcommand prints the version of the VCDB SQL scripts bundled with your version of vcdb-tool. The command does not require any specific CLI options to run.

  • Linux

  • Windows CMD

./vcdb database scripts-version
vcdb database scripts-version

The SQL scripts version is printed to the console in the log messages. On error, the log shows the corresponding message to help identify the cause. An example of the log output for a successful command is shown below.

$ vcdb database scripts-version
[16:00:20 INFO] Starting vcdb-tool, version 1.0.0.
[16:00:20 INFO] Loading plugins...
[16:00:20 INFO] Executing 'database scripts-version' command.
[16:00:20 INFO] Reading version of the bundled VCDB SQL scripts...
[16:00:20 INFO] VCDB scripts version: 5.0.0
[16:00:20 INFO] Total execution time: 00 s.
[16:00:20 INFO] vcdb successfully completed.

The scripts version can optionally be written as JSON using the --output option. If a file path is provided, the JSON output will be written to that file. If - is specified instead of a file path, the JSON output will be written to stdout. This JSON output can be easily piped to and processed by external tools.

The following examples demonstrate the usage of the --output option.

  • Linux

  • Windows CMD

./vcdb database scripts-version [...] -o version.json      # write JSON to a file
./vcdb database scripts-version [...] -o -                 # write JSON to stdout
./vcdb database scripts-version [...] -o - > version.json  # redirect stdout to a file
vcdb database scripts-version [...] -o version.json      # write JSON to a file
vcdb database scripts-version [...] -o -                 # write JSON to stdout
vcdb database scripts-version [...] -o - > version.json  # redirect stdout to a file

The JSON output is minimal and contains only the "scriptsVersion".

{
  "scriptsVersion": "5.0.0"
}
The structure of the JSON output is defined by the JSON Schema file scripts-version.json.schema, which is located in the json-schema folder of the vcdb-tool installation directory.