Connection Details

Most vcdb-tool commands require a connection to a VCDB v5 instance. Connection details can be specified via command-line options, argument files, JSON configuration files, or environment variables.

Using command-line 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.

-S, --db-schema=<schema>

Schema to use when connecting to the VCDB.

citydb or username

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

Use --db-host to specify the network name or IP address of the database server. The --db-name option defines the name of the VCDB v5 instance, while --db-schema sets the database schema to connect to. For PostgreSQL, the default schema is citydb. Additional schemas can be created using the database scripts included in the VCDB v5 software package.

The username and password for connecting to the VCDB are set with --db-username and --db-password. You can provide the password directly or leave it empty to be prompted for input before connecting. The prompt will time out after 60 seconds. If this option is omitted, vcdb-tool will attempt to connect without a password.

In addition to the standard connection parameters, database-specific properties can be provided through the --db-property option to configure the JDBC driver behavior. These properties should be specified as a comma-separated list of property=value pairs.

The example below shows how to use the database connection options. It includes the PostgreSQL-specific ssl parameter to establish an SSL connection.

  • Linux

  • Windows CMD

./vcdb export citygml \
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret \
    --db-property=ssl=true \
    -o output.gml
vcdb export citygml ^
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret ^
    --db-property=ssl=true ^
    -o output.gml
Consult the database documentation for an overview of supported JDBC connection properties. For PostgreSQL, further details can be found here.

Using configuration files

vcdb-tool supports loading options and settings from a JSON-encoded configuration file, as described here. The JSON structure for storing database connection options is illustrated below.

{
  "databaseOptions": {
    "connections": {
      "myFirstConnection": {
        "host": "localhost",
        "port": 5432,
        "database": "citydb",
        "schema": "citydb",
        "user": "citydb_user",
        "password": "mySecret",
        "properties": {
          "ssl": true
        },
        "poolOptions": {
          "loginTimeout": 120
        }
      },
      "mySecondConnection": {
        "host": "the.host.de",
        "database": "3dcitydb",
        "user": "citydb_user",
        "password": "mySecret"
      }
    },
    "defaultConnection": "myFirstConnection"
  }
}

Database connection options are defined in the "databaseOptions" object within the configuration file. The "connections" key contains one or more connection configurations, each identified by a unique, user-defined name. In the example above, myFirstConnection and mySecondConnection define connections to different VCDB v5 instances with distinct settings. The "defaultConnection" key specifies which connection to use. It can be omitted if only one connection is defined.

Each connection can include the following properties, closely aligned with the corresponding command-line options:

Option Description Default value

"host"

Name of the host on which the VCDB is running.

"port"

Port of the VCDB server.

5432

"database"

Name of the VCDB database to connect to.

"schema"

Schema to use when connecting to the VCDB.

citydb or username

"user"

Username to use when connecting to the VCDB.

"password"

Password to use when connecting to the VCDB.

"properties"

Database-specific connection properties provided as key-value pairs.

"poolOptions"

Connection pool options provided as key-value pairs.

The "poolOptions" property is available only in the JSON configuration and is not exposed as a command-line option. It configures internal connection pool behavior. Currently, the only supported option is "loginTimeout", which sets the maximum time (in seconds) to wait for a connection attempt before timing out (default: 60 seconds). Additional pool options may be added in future versions.

You can use a configuration file as shown below.

vcdb export citygml --config-file=/path/to/config.json -o output.gml
Connection options from a configuration file can be used alongside command-line options, in which case command-line options take precedence.
Storing passwords in a configuration file in clear text may pose a security risk. Consider using an environment variable for the password instead, or leave the --db-password option empty to be prompted.

Using argument files

You can also store the database connection options in an argument file and reference it in the command using the @ symbol. The contents of the argument file are automatically expanded into the argument list. For more information on using argument files, refer to the section here.

For example, suppose the following database options are stored in an @-file located at /home/foo/db-args:

--db-host=localhost
--db-port=5432
--db-name=citdb
--db-schema=citydb
--db-username=citydb_user
--db-password=mySecret
--db-property=ssl=true

This @-file can then be used as shown below.

vcdb export citygml @/home/foo/db-args -o output.gml
Storing passwords in an argument file in clear text may pose a security risk. Consider using an environment variable for the password instead, or leave the --db-password option empty to be prompted.

Using environment variables

Environment variables allow for dynamic definition of database connection details. This approach is useful for automated scripts, CI/CD pipelines, or when credentials should not be hard-coded. It is also ideal for running vcdb-tool in Docker environments, where environment variables can be easily passed into containers at runtime.

The following environment variables for defining database connection details are supported by vcdb-tool and closely align with the command-line options:

Environment variable Description

CITYDB_HOST

Name of the host on which the VCDB is running.

CITYDB_PORT

Port of the VCDB server.

CITYDB_NAME

Name of the VCDB database to connect to.

CITYDB_SCHEMA

Schema to use when connecting to the VCDB.

CITYDB_USER

Username to use when connecting to the VCDB.

CITYDB_PASSWORD

Password to use when connecting to the VCDB.

CITYDB_CONN_PROPS

Database-specific connection properties provided as comma-separated list of property=value pairs.

The following command demonstrates how to use these environment variables to dynamically specify database connection details.

  • Linux

  • Windows CMD

export CITYDB_HOST=localhost
export CITYDB_PORT=5432
export CITYDB_NAME=citdb
export CITYDB_SCHEMA=citydb
export CITYDB_USER=citydb_user
export CITYDB_PASSWORD=mySecret
export CITYDB_CONN_PROPS=ssl=true

./vcdb export citygml -o output.gml
set CITYDB_HOST=localhost
set CITYDB_PORT=5432
set CITYDB_NAME=citdb
set CITYDB_SCHEMA=citydb
set CITYDB_USER=citydb_user
set CITYDB_PASSWORD=mySecret
set CITYDB_CONN_PROPS=ssl=true

vcdb export citygml -o output.gml
Environment variables can be used alongside command-line options and configuration files. However, they have the lowest precedence and are overridden by these options.