Connect-Befehl

Mit dem connect Befehl kann einfach überprüft werden, ob eine Verbindung zu einer bestehenden VCDB v5 Instanz hergestellt werden kann, bevor nachfolgende Operationen wie das Importieren oder Exportieren von Daten ausgeführt werden.

Synopsis

vcdb connect [OPTIONS]

Optionen

Der connect Befehl erbt globale Optionen vom Hauptbefehl vcdb. Zusätzlich definiert er allgemeine Datenbank-Verbindungsoptionen und unterstützt die Ausgabe des Verbindungsstatus im JSON-Format.

Globale Optionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`[@<filename>…]`	Eine oder mehrere Argumentdateien mit Optionen.
`-h`, `--help`	Hilfenachricht anzeigen und beenden.
`-V`, `--version`	Versionsinformationen ausgeben und beenden.
`--config-file=<file>`	Konfiguration aus dieser Datei laden.
`-L`, `--log-level=<level>`	Log-Level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`.	`info`
`--log-file=<file>`	Log-Nachrichten in diese Datei schreiben.
`--quiet`	Deaktiviert Log-Nachrichten auf der Konsole.
`--pid-file=<file>`	Datei mit der Prozess-ID erstellen.
`--plugins=<dir>`	Plugins aus diesem Verzeichnis laden.
`--use-plugin=<plugin[=true\|false]> [,<plugin[=true\|false]>…]`	Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.	`true`

[@<filename>…]

Eine oder mehrere Argumentdateien mit Optionen.

-h, --help

Hilfenachricht anzeigen und beenden.

-V, --version

Versionsinformationen ausgeben und beenden.

--config-file=<file>

Konfiguration aus dieser Datei laden.

-L, --log-level=<level>

Log-Level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Log-Nachrichten in diese Datei schreiben.

--quiet

Deaktiviert Log-Nachrichten auf der Konsole.

--pid-file=<file>

Datei mit der Prozess-ID erstellen.

--plugins=<dir>

Plugins aus diesem Verzeichnis laden.

--use-plugin=<plugin[=true|false]> [,<plugin[=true|false]>…]

Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.

true

Weitere Informationen zu den globalen Optionen und Nutzungshinweise siehe hier.

Ausgabeoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-o`, `--output=<file\|->`	Ausgabe in eine JSON-Datei schreiben. Mit `-` wird nach `stdout` ausgegeben.

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

Ausgabe in eine JSON-Datei schreiben. Mit - wird nach stdout ausgegeben.

Datenbank-Verbindungsoptionen

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.

Weitere Informationen zu den Datenbank-Verbindungsoptionen und Nutzungshinweise siehe hier.

Verwendung

Testen einer Verbindung

Um die Verbindung zu einer VCDB v5 Instanz zu testen, muss der connect Befehl mit den Verbindungsparametern für die entsprechende Datenbank ausgeführt werden. Wie hier beschrieben, können die Verbindungsparameter über die oben beschriebenen Kommandozeilenoptionen oder alternativ durch eine JSON-Konfigurationsdatei oder Umgebungsvariablen definiert werden.

Das folgende Beispiel zeigt die Ausführung des Befehls mit Kommandozeilenoptionen:

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

Beim Ausführen des Befehls werden Log-Meldungen in der Konsole ausgegeben, die den Fortschritt des Verbindungsversuchs dokumentieren. Bei erfolgreicher Verbindung werden die Datenbankdetails der verbundenen VCDB-Instanz angezeigt. Im Fehlerfall enthält die Log-Ausgabe eine entsprechende Fehlermeldung, die bei der Identifizierung der Fehlerursache unterstützt. Darüber hinaus verwendet der Befehl Exit-Codes, die eine automatische Auswertung des Verbindungsversuchs ermöglichen:

0: Verbindung erfolgreich.
1: Verbindung aufgrund von Fehlern oder Problemen fehlgeschlagen.
2: Ungültige Eingabe für eine Option oder einen Parameter.

JSON-Ausgabe

Der Verbindungsstatus kann mithilfe der --output Option auch im JSON-Format ausgegeben werden. Wird ein Dateipfad angegeben, dann wird die JSON-Ausgabe in diese Datei geschrieben. Wird anstelle eines Dateipfads - verwendet, dann erfolgt die JSON-Ausgabe auf stdout. Auf diese Weise lässt sich die JSON-Ausgabe einfach umleiten und mit externen Werkzeugen weiterverarbeiten.

Die folgenden Beispiele zeigen die Verwendung der Option --output.

Linux
Windows CMD

./vcdb connect [...] -o status.json      # JSON in Datei schreiben
./vcdb connect [...] -o -                # JSON auf stdout ausgeben
./vcdb connect [...] -o - > status.json  # stdout in Datei umleiten

vcdb connect [...] -o status.json      # JSON in Datei schreiben
vcdb connect [...] -o -                # JSON auf stdout ausgeben
vcdb connect [...] -o - > status.json  # stdout in Datei umleiten

Die JSON-Ausgabe enthält Informationen darüber, ob die Verbindung erfolgreich war oder fehlgeschlagen ist, zusammen mit relevanten Datenbankdetails oder Fehlermeldungen.

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

Die JSON-Struktur enthält folgende Angaben:

"connectionStatus": Ergebnis des Verbindungsversuchs, entweder success oder failure.
"connection": Die für den Verbindungsversuch verwendeten Parameter.
"database" (bei erfolgreicher Verbindung): Datenbankname, Version, DBMS-spezifische Erweiterungen, Eigenschaften und CRS-Details.
"error" (im Fehlerfall): Eine oder mehrere Fehlerursachen mit Beschreibung und zugehöriger Exception zur Identifzierung des Verbindungsproblems.

Die Struktur der JSON-Ausgabe wird durch die JSON Schema-Datei connection-status.json.schema definiert, die sich im Ordner json-schema des vcdb-tool Installationsverzeichnisses befindet.