Create database command

The database create command sets up a new VCDB v5 instance in the target database.

Synopsis

vcdb database create [OPTIONS] COMMAND

Options

The database create command inherits global options from the main vcdb command and script options from its parent database command. Additionally, it provides options for setting up and configuring a new 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.

Create database options

Option Description Default value

-s, --srid=<srid>

SRID to use for the VCDB instance.

--crs-name=<name>

Name of the CRS to use for the VCDB instance.

urn:ogc:def:crs:EPSG::
<srid>

--enable-changelog

Enable changelog extension for the VCDB instance.

--drop-existing

First drop the existing VCDB instance.

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

Write VCDB instance info to JSON. Use - for stdout.

Database connection options

Option Description Default value

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

Name of the host on which the VCDB is created.

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

Port of the VCDB server.

5432

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

Name of the database to use for the VCDB instance. Will be created using the admin user if it does not exist (if supported by the DBMS).

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

Username of the VCDB owner. Will be created using the admin user if it does not exist.

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

Password to use for the VCDB owner. Leave empty to be prompted.

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

Database-specific connection properties.

-a, --db-admin-username=<user>

Username with sufficient privileges to manage databases, users, and extensions.

-w, --db-admin-password
[=<password>]

Password to use for the admin user. Leave empty to be prompted.

--db-admin-database=<database>

Database for the admin user to connect to.

postgres for PostgreSQL

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

Usage

Target database and VCDB instance owner

To create a new VCDB instance using the create command, provide the necessary connection details to the target 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 target database and owner for the new VCDB instance are specified using the following mandatory options:

  • --db-name: The target database in which the VCDB instance will be created.

  • --db-username: The user who will become the owner of the VCDB instance.

By default, the command assumes that both the target database and the owner already exist. If either is missing or misconfigured — for example, due to missing database extensions or insufficient privileges — the command will terminate with an error.

If the target database already contains an existing VCDB instance, you can use the --drop-existing flag to first remove the existing instance before creating a new one. This requires that the user provided via --db-username has sufficient privileges to remove the existing VCDB instance.

The chapter on setting up a VCDB using the shell installation scripts explains how to create the target database and owner manually.

Running in admin mode

If you have access to a database user with sufficient administration privileges, you can run the create command in admin mode. In this mode, the target database and owner are automatically created if they do not exist, ensuring that the correct settings and privileges are applied. Admin mode thus provides a convenient way to set up all required database objects in a single step.

To use admin mode, provide the following additional connection options:

  • --db-admin-username: A database user with sufficient administrative privileges.

  • --db-admin-password: The password of the admin user. Leave empty to be prompted.

  • --db-admin-database: The database the admin user should connect to. This option is only required if a database is needed to establish the connection. For PostgreSQL, the postgres database is used as the default.

Existing databases and users will be used as-is and will not be modified. For example, if the target database already exists but lacks mandatory extensions, the create command will fail even in admin mode.

Specifying the coordinate reference system

For each VCDB instance, a coordinate reference system (CRS) must be specified to define the spatial reference of the geometries stored in the database. Use the mandatory --srid option to provide the database-specific SRID (Spatial Reference ID) of the CRS you want to assign. In most cases, the SRID matches the EPSG code of the CRS.

The option --crs-name lets you define an OGC-compliant name of the CRS. The CRS name is, for instance, included in CityGML/CityJSON files when exporting data from the database. If omitted, the default URN urn:ogc:def:crs:EPSG::<SRID> is used, where <SRID> is replaced with the value provided via --srid.

The coordinate reference system can be changed at any time after setup using the database function citydb_pkg.change_schema_srid. Refer to the database functions section for more information.

Changelog extension

You can choose whether to enable the changelog extension for the new VCDB instance. This extension adds a table to the VCDB schema that tracks insert, delete, and update operations on top-level city objects. To enable the changelog extension, use the --enable-changelog flag.

When the changelog extension is enabled, insert, delete, and update operations may take longer due to the additional tracking.

Output and logging

The following example illustrates the usage of the create command.

  • Linux

  • Windows CMD

./vcdb database create \
    -H localhost \
    -d citydb \                        # target database
    -u citydb_user \                   # VCDB instance owner
    -p mySecret \
    --db-admin-user admin_user \       # admin user to create the database and owner
    --db-admin-password adminSecret \
    --srid 25832 \
    --enable-changelog
vcdb database create ^
    -H localhost ^
    -d citydb ^                        # target database
    -u citydb_user ^                   # VCDB instance owner
    -p mySecret ^
    --db-admin-user admin_user ^       # admin user to create the database and owner
    --db-admin-password adminSecret ^
    --srid 25832 ^
    --enable-changelog

When the create command is executed, log messages are printed to the console showing the progress of the operation. On success, the database details of the newly created VCDB instance are displayed on the console. On error, the log shows the corresponding error 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 database details of the VCDB instance 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 create [...] -o new-vcdb.json      # write JSON to a file
./vcdb database create [...] -o -                  # write JSON to stdout
./vcdb database create [...] -o - > new-vcdb.json  # redirect stdout to a file
vcdb database create [...] -o new-vcdb.json      # write JSON to a file
vcdb database create [...] -o -                  # write JSON to stdout
vcdb database create [...] -o - > new-vcdb.json  # redirect stdout to a file

The JSON output contains the connection details, such as the target database and the VCDB instance owner, along with relevant database metadata. It uses the same structure as the JSON output of the info command.

{
  "connection": {
    "host": "localhost",
    "port": 5432,
    "database": "citydb",
    "schema": "citydb",
    "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": true,
    "crs": {
      "srid": 25832,
      "identifier": "urn:ogc:def:crs:EPSG::25832",
      "name": "ETRS89 / UTM zone 32N"
    }
  }
}
The structure of the JSON output is defined by the JSON Schema file connection-info.json.schema, which is located in the json-schema folder of the vcdb-tool installation directory.