Connect Command

The connect command can be used to quickly verify whether a connection to a VCDB v5 instance can be established before performing tasks such as importing or exporting data.

Synopsis

vcdb connect [OPTIONS]

Options

The connect command inherits global options from the main vcdb command. Additionally, it defines general database connection options and supports outputting the connection status in JSON format.

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.

Output options

Option Description Default value

-o, --output=<file|->

Write output as a JSON file. Use - for stdout.

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.

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

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

Usage

Testing a connection

To test a connection to a VCDB v5 instance, run the connect command and provide the corresponding connection details for the 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 example below shows how to run the command using CLI options:

  • Linux

  • Windows CMD

./vcdb connect \
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret \
    -S mySchema
vcdb connect ^
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret ^
    -S mySchema

When the command is executed, log messages are printed to the console showing the progress of the connection attempt. On success, the database details of the connected VCDB instance are displayed. On error, the log shows the corresponding error message to help identify the cause. The command also returns exit codes to allow automatic interpretation of the connection status:

  • 0: Connection successful.

  • 1: Connection failed due to errors or issues.

  • 2: Invalid input for an option or parameter.

JSON output

The connection status can also be output in JSON format by 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 connect [...] -o status.json      # write JSON to a file
./vcdb connect [...] -o -                # write JSON to stdout
./vcdb connect [...] -o - > status.json  # redirect stdout to a file
vcdb connect [...] -o status.json      # write JSON to a file
vcdb connect [...] -o -                # write JSON to stdout
vcdb connect [...] -o - > status.json  # redirect stdout to a file

The JSON output contains information about whether the connection succeeded or failed, along with relevant database details or error messages.

  • Success example

  • Error example

{
  "connectionStatus": "success",
  "connection": {
    "host": "localhost",
    "port": 5432,
    "database": "citydb",
    "schema": "mySchema",
    "user": "citydb_user"
  },
  "database": {
    "name": "VC Database",
    "version": "5.0.0",
    "dbms": {
      "name": "PostgreSQL",
      "version": "17.2",
      "properties": {
        "postgis": {
          "name": "PostGIS",
          "value": "3.5.0"
        },
        "postgis_sfcgal": {
          "name": "SFCGAL",
          "value": "1.5.2"
        }
      }
    },
    "hasChangelogEnabled": false,
    "crs": {
      "srid": 25832,
      "identifier": "urn:ogc:def:crs:EPSG::25832",
      "name": "ETRS89 / UTM zone 32N"
    }
  }
}
{
  "connectionStatus": "failure",
  "connection": {
    "host": "localhost",
    "port": 5432,
    "database": "citydb",
    "schema": "mySchema",
    "user": "citydb_user"
  },
  "error": {
    "causes": [
      {
        "message": "The requested schema 'mySchema' is not a VCDB schema.",
        "exception": "org.citydb.database.DatabaseException"
      }
    ]
  }
}

The JSON structure contains the following details:

  • "connectionStatus": The connection result, either success or failure.

  • "connection": The connection details used for the attempt.

  • "database" (present on success): Database name, version, DBMS-specific extensions, properties, and CRS details.

  • "error" (present on failure): One or more causes with descriptive messages and associated exceptions to help identify the connection issue.

The structure of the JSON output is defined by the JSON Schema file connection-status.json.schema, which is located in the json-schema folder of the vcdb-tool installation directory.