Verbindungsparameter

Die meisten vcdb-tool Befehle erfordern eine Verbindung zu einer VCDB v5 Instanz. Verbindungsparameter können über Kommandozeilenoptionen, Argumentdateien, JSON-Konfigurationsdateien oder Umgebungsvariablen angegeben werden.

Verwendung von Kommandozeilenoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-H`, `--db-host=<host>`	Hostname des VCDB Datenbankservers.
`-P`, `--db-port=<port>`	Port des VCDB Datenbankservers.	5432
`-d`, `--db-name=<database>`	Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.
`-S`, `--db-schema=<schema>`	Schema, das beim Verbinden zur VCDB verwendet werden soll.	`citydb` oder Benutzername
`-u`, `--db-username=<user>`	Benutzername für die Verbidung zur VCDB.
`-p`, `--db-password [=<password>]`	Passwort für die Verbidung zur VCDB. Leer lassen, um zur Eingabe aufgefordert zu werden.
`--db-property=<property=value> [,<proeprty=value>…]`	Datenbankspezifische Verbindungsparameter.

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

Hostname des VCDB Datenbankservers.

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

Port des VCDB Datenbankservers.

5432

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

Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.

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

Schema, das beim Verbinden zur VCDB verwendet werden soll.

citydb oder Benutzername

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

Benutzername für die Verbidung zur VCDB.

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

Passwort für die Verbidung zur VCDB. Leer lassen, um zur Eingabe aufgefordert zu werden.

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

Datenbankspezifische Verbindungsparameter.

Die Option --db-host gibt den Hostnamen oder die IP-Adresse des Datenbankservers an. Mit --db-name wird der Namen der VCDB v5 Instanz angegeben, während --db-schema das Datenbankschema für die festlegt, das für die Verbindung verwendet werden soll. Für PostgreSQL ist das Standardschema citydb. Weitere Schemas können mithilfe der Datenbankskripte angelegt werden, die im VCDB v5 Softwarepaket enthalten sind.

Der Benutzername und das Passwort für die Verbindung zur VCDB werden über --db-username und --db-password angegeben. Das Passwort kann entweder direkt übergeben oder weggelassen werden, um vor der Verbindung zur Eingabe des Passworts aufgefordert zu werden. Die Eingabeaufforderung läuft nach 60 Sekunden ab. Wenn die Option --db-password nicht angegeben wird, versucht vcdb-tool, eine Verbindung ohne Passwort herzustellen.

Zusätzlich zu den dargestellten Verbindungsparametern können mit der Options --db-property weitere datenbankspezifische Einstellungen vorgenommen werden, um das Verhalten des JDBC-Treibers zu konfigurieren. Diese Eigenschaften müssem als kommaseparierte Liste von property=value Paaren übergeben werden.

Das folgende Beispiel zeigt die Verwendung der Verbindungsparameter. Zusätzlich zu den normalen Optionen wird auch der PostgreSQL-spezifische Parameter ssl angegeben, um eine SSL-Verbindung herzustellen.

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

Weitere Informationen zu den unterstützten JDBC-Verbindungsoptionen finden Sie in der Dokumentation Ihres Datenbanksystems. Für PostgreSQL erhalten Sie nähere Details hier.

Verwendung von Konfigurationsdateien

vcdb-tool unterstützt das Laden von Optionen und Einstellungen aus einer Konfigurationsdatei im JSON-Format (siehe hier). Die JSON-Struktur zur Speicherung der Verbindungsparameter ist nachfolgend dargestellt.

{
  "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"
  }
}

Datenbank-Verbindungsoptionen werden im Objekt "databaseOptions" innerhalb der Konfigurationsdatei definiert. Das Attribute "connections" enthält eine oder mehrere Verbindungskonfigurationen, die jeweils mit einem eindeutigen, benutzerdefinierten Namen versehen werden. Im obigen Beispiel definieren myFirstConnection und mySecondConnection Verbindungen zu verschiedenen VCDB v5 Instanzen mit unterschiedlichen Einstellungen. Über "defaultConnection" wird festgelegt, welche Verbindung verwendet werden soll. Es kann weggelassen werden, wenn nur eine Verbindung definiert ist.

Jede Verbindung kann die folgenden Eigenschaften enthalten, die eng an die entsprechenden Kommandozeilen- Optionen angelehnt sind:

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`"host"`	Hostname des VCDB Datenbankservers.
`"port"`	Port des VCDB Datenbankservers.	5432
`"database"`	Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.
`"schema"`	Schema, das beim Verbinden zur VCDB verwendet werden soll.	`citydb` oder Benutzername
`"user"`	Benutzername für die Verbidung zur VCDB.
`"password"`	Passwort für die Verbindung zur VCDB.
`"properties"`	Datenbankspezifische Verbindungsparameter als Key-Value Paare.
`"poolOptions"`	Optionen zur Konfiguration des Verbindungspools.

"host"

Hostname des VCDB Datenbankservers.

"port"

Port des VCDB Datenbankservers.

5432

"database"

Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.

"schema"

Schema, das beim Verbinden zur VCDB verwendet werden soll.

citydb oder Benutzername

"user"

Benutzername für die Verbidung zur VCDB.

"password"

Passwort für die Verbindung zur VCDB.

"properties"

Datenbankspezifische Verbindungsparameter als Key-Value Paare.

"poolOptions"

Optionen zur Konfiguration des Verbindungspools.

Die Eigenschaft "poolOptions" ist nur in der JSON-Konfiguration verfügbar und wird nicht als Kommandozeilenoption bereitgestellt. Sie konfiguriert das Verhalten des internen Verbindungspools. Derzeit wird nur die Option "loginTimeout" unterstützt, die die maximale Zeit (in Sekunden) festlegt, die bei einem Verbindungsversuch gewartet wird, bevor ein Timeout auftritt (Standard: 60 Sekunden). Zusätzliche Pool- Optionen können in zukünftigen Versionen hinzugefügt werden.

Eine JSON-basierte Konfigurationsdatei kann wie unten gezeigt verwendet werden.

vcdb export citygml --config-file=/path/to/config.json -o output.gml

Verbindungsoptionen aus einer Konfigurationsdatei können zusammen mit Kommandozeilenoptionen verwendet werden, wobei Kommandozeilenoptionen Vorrang haben.

Das Speichern von Passwörtern im Klartext in einer Konfigurationsdatei kann ein Sicherheitsrisiko darstellen. Es sollte stattdessen eine Umgebungsvariable für das Passwort verwendet oder die --db-password-Option leer gelassen werden, um zur Eingabe des Passworts in der Kommandozeile aufgefordert zu werden.

Verwendung von Argumentdateien

Verbindungsparameter können auch in einer Argumentdatei gespeichert und in der Befehlszeile mit dem @- Symbol referenziert werden. Der Inhalt der Argumentdatei wird automatisch in die Argumentliste eingefügt. Weitere Informationen zur Verwendung von Argumentdateien finden Sie im entsprechenden Abschnitt hier.

Sind beispielsweise die folgenden Verbindungsparameter in einer @-Datei unter /home/foo/db-args gespeichert:

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

Dann kann diese @-Datei wir folgt beim Aufruf von vcdb-tool verwendet werden:

vcdb export citygml @/home/foo/db-args -o output.gml

Das Speichern von Passwörtern im Klartext in einer Argumentdatei kann ein Sicherheitsrisiko darstellen. Es sollte stattdessen eine Umgebungsvariable für das Passwort verwendet oder die --db-password-Option leer gelassen werden, um zur Eingabe des Passworts in der Kommandozeile aufgefordert zu werden.

Verwendung von Umgebungsvariablen

Umgebungsvariablen ermöglichen die dynamische Definition von Verbindungsparametern für die Datenbank. Die Verwendung von Umgebungsvariablen is besonders nützlich für automatisierte Skripte, CI/CD-Pipelines oder wenn Anmeldedaten nicht hartkodiert übergeben werden sollen. Er ist auch ideal für die Ausführung von vcdb-tool in Docker-Umgebungen, wo Umgebungsvariablen zur Laufzeit einfach in Container übergeben werden können.

Die folgenden Umgebungsvariablen zur Definition der Datenbankverbindung werden von vcdb-tool unterstützt und sind eng an die entsprechenden Kommandozeilenoptionen angelehnt:

Umgebungsvariable Beschreibung

Umgebungsvariable	Beschreibung
`CITYDB_HOST`	Hostname des VCDB Datenbankservers.
`CITYDB_PORT`	Port des VCDB Datenbankservers.
`CITYDB_NAME`	Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.
`CITYDB_SCHEMA`	Schema, das beim Verbinden zur VCDB verwendet werden soll.
`CITYDB_USER`	Benutzername für die Verbidung zur VCDB.
`CITYDB_PASSWORD`	Passwort für die Verbindung zur VCDB.
`CITYDB_CONN_PROPS`	Datenbankspezifische Verbindungsparameter als kommaseparierte Liste von `property=value` Paaren.

CITYDB_HOST

Hostname des VCDB Datenbankservers.

CITYDB_PORT

Port des VCDB Datenbankservers.

CITYDB_NAME

Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.

CITYDB_SCHEMA

Schema, das beim Verbinden zur VCDB verwendet werden soll.

CITYDB_USER

Benutzername für die Verbidung zur VCDB.

CITYDB_PASSWORD

Passwort für die Verbindung zur VCDB.

CITYDB_CONN_PROPS

Datenbankspezifische Verbindungsparameter als kommaseparierte Liste von property=value Paaren.

Der folgende Befehl zeigt, wie diese Umgebungsvariablen zur dynamischen Definition von Verbindungsparametern verwendet werden können.

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

Umgebungsvariablen können zusammen mit Kommandozeilenoptionen und Konfigurationsdateien verwendet werden. Sie haben jedoch die niedrigste Priorität und werden von diesen Alternativen überschrieben.