Datenbank erstellen

Der database create Befehl erstellt eine neue VCDB v5 Instanz in der Zieldatenbank.

Synopsis

vcdb database create [OPTIONS] COMMAND

Optionen

Der database create Befehl erbt globale Optionen vom Hauptbefehl vcdb sowie Skriptoptionen von seinem übergeordneten database Befehl. Zusätzlich stellt er Optionen zum Aufsetzen und Konfigurieren einer VCDB-Instanz bereit.

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.

Skriptoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-c`, `--client=<file>`	Pfad zur ausführbaren Datei des Datenbank-Clients.	Client wird im `PATH` gesucht
`--timeout=<seconds>`	Zeit in Sekunden, die auf den Abschluss der Operation gewartet wird.	60

-c, --client=<file>

Pfad zur ausführbaren Datei des Datenbank-Clients.

Client wird im PATH gesucht

--timeout=<seconds>

Zeit in Sekunden, die auf den Abschluss der Operation gewartet wird.

Weitere Informationen zu den Skriptoptionen und Nutzungshinweise siehe hier.

Optionen zum Aufsetzen der Datenbank

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-s`, `--srid=<srid>`	SRID für die VCDB-Instanz.
`--crs-name=<name>`	Name des CRS für die VCDB-Instanz.	urn:ogc:def:crs:EPSG:: `<srid>`
`--enable-changelog`	Changelog-Erweiterung für die VCDB-Instanz aktivieren.
`--drop-existing`	Zuerst eine vorhandene VCDB-Instanz löschen.
`-o`, `--output=<file\|->`	Details zur VCDB-Instanz in eine JSON-Datei schreiben. Mit `-` wird nach `stdout` ausgegeben.

-s, --srid=<srid>

SRID für die VCDB-Instanz.

--crs-name=<name>

Name des CRS für die VCDB-Instanz.

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

--enable-changelog

Changelog-Erweiterung für die VCDB-Instanz aktivieren.

--drop-existing

Zuerst eine vorhandene VCDB-Instanz löschen.

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

Details zur VCDB-Instanz in eine JSON-Datei schreiben. Mit - wird nach stdout ausgegeben.

Datenbank-Verbindungsoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-H`, `--db-host=<host>`	Hostname des Datenbankservers, auf dem die VCDB erstellt wird.
`-P`, `--db-port=<port>`	Port des VCDB Datenbankservers.	5432
`-d`, `--db-name=<database>`	Name der Datenbank, in der die VCDB-Instanz erstellt werden soll. Wird bei Bedarf mit dem Admin-Benutzer erstellt (sofern vom DBMS unterstützt).
`-u`, `--db-username=<user>`	Benutzername des VCDB Besitzers. Wird bei Bedarf mit dem Admin-Benutzer erstellt.
`-p`, `--db-password [=<password>]`	Passwort des VCDB Besitzers. Leer lassen, um zur Eingabe aufgefordert zu werden.
`--db-property=<property=value> [,<property=value>…]`	Datenbankspezifische Verbindungsparameter.
`-a`, `--db-admin-username=<user>`	Benutzername mit ausreichenden Rechten zur Verwaltung von Datenbanken, Benutzern und Erweiterungen.
`-w`, `--db-admin-password [=<password>]`	Passwort des Admin-Benutzers. Leer lassen, um zur Eingabe aufgefordert zu werden.
`--db-admin-database=<database>`	Datenbank, mit der sich der Admin-Benutzer verbinden soll.	`postgres` für PostgreSQL

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

Hostname des Datenbankservers, auf dem die VCDB erstellt wird.

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

Port des VCDB Datenbankservers.

5432

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

Name der Datenbank, in der die VCDB-Instanz erstellt werden soll. Wird bei Bedarf mit dem Admin-Benutzer erstellt (sofern vom DBMS unterstützt).

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

Benutzername des VCDB Besitzers. Wird bei Bedarf mit dem Admin-Benutzer erstellt.

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

Passwort des VCDB Besitzers. Leer lassen, um zur Eingabe aufgefordert zu werden.

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

Datenbankspezifische Verbindungsparameter.

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

Benutzername mit ausreichenden Rechten zur Verwaltung von Datenbanken, Benutzern und Erweiterungen.

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

Passwort des Admin-Benutzers. Leer lassen, um zur Eingabe aufgefordert zu werden.

--db-admin-database=<database>

Datenbank, mit der sich der Admin-Benutzer verbinden soll.

postgres für PostgreSQL

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

Im Gegensatz zu anderen Befehlen steht die Option --db-schema für den database create Befehl nicht zur Verfügung.

Verwendung

Zieldatenbank und Besitzer der VCDB-Instanz

Um eine neue VCDB-Instanz mit dem create Befehl zu erstellen, müssen die Verbindungsparameter zur Zieldatenbank angegeben werden. Wie hier beschrieben, können die Verbindungsparameter über die oben beschriebenen Kommandozeilenoptionen oder alternativ durch eine JSON-Konfigurationsdatei oder Umgebungsvariablen definiert werden.

Die Zieldatenbank und der Besitzer der neuen VCDB-Instanz werden über die folgenden obligatorischen Optionen definiert:

--db-name: Die Zieldatenbank, in welcher die VCDB-Instanz erstellt wird.
--db-username: Der Benutzer, der Besitzer der VCDB-Instanz werden soll.

Standardmäßig wird davon ausgegangen, dass sowohl die Zieldatenbank als auch der Besitzer bereits angelegt wurden und existieren. Falls nur eine der beiden Voraussetzungen nicht erfüllt ist, oder entweder die Zieldatenbank oder der Benutzer falsch konfiguriert ist — beispielsweise aufgrund fehlender Datenbankerweiterungen oder unzureichender Berechtigungen — bricht der Befehl mit einem Fehler ab.

Wenn die Zieldatenbank bereits eine bestehende VCDB-Instanz enthält, kann mit der Option --drop-existing zunächst die bestehende Instanz entfernt werden, bevor die neue Instanz erstellt wird. Dazu muss der über --db-username angegebene Benutzer über ausreichende Berechtigungen zum Entfernen der VCDB-Instanz verfügen.

Im Kapitel zum Aufsetzen einer VCDB mithilfe der Shell-Installationsskripten wird erläutert, wie die Zieldatenbank und der Besitzer manuell erstellt werden können.

Ausführen im Admin-Mode

Wenn Sie Zugriff auf einen Datenbankbenutzer mit ausreichenden Administratorrechten haben, kann der create Befehl auch im Admin-Modus ausgeführt werden. In diesem Modus werden die Zieldatenbank und der Besitzer automatisch erstellt, falls sie noch nicht vorhanden sind. Dadurch wird sichergestellt, dass die richtigen Einstellungen und Berechtigungen angewendet werden. Der Admin-Modus bietet somit eine bequeme Möglichkeit, alle erforderlichen Datenbankobjekte in nur einem Schritt anzulegen und einzurichten.

Um den Admin-Modus zu verwenden, müssen die folgenden zusätzlichen Verbindungsoptionen angegeben werden:

--db-admin-username: Ein Datenbankbenutzer mit ausreichenden Administratorrechten.
--db-admin-password: Das Passwort des Admin-Benutzers. Leer lassen, um zur Eingabe aufgefordert zu werden.
--db-admin-database: Die Datenbank, mit der sich der Admin-Benutzer verbinden soll. Diese Option ist nur erforderlich, wenn eine Datenbank zum Herstellen einer Verbindung erforderlich ist. Für PostgreSQL wird standardmäßig die Datenbank postgres verwendet.

Bereits vorhandene Datenbanken und Benutzer werden unverändert übernommen und nicht angepasst. Wenn beispielsweise die Zieldatenbank bereits existiert, aber erforderliche Erweiterungen fehlen, schlägt der create Befehl auch im Admin-Modus fehl.

Koordinatenreferenzsystem festlegen

Für jede VCDB-Instanz muss ein Koordinatenreferenzsystem (CRS) angegeben werden, das die räumliche Referenz für die in der Datenbank gespeicherten Geometrien definiert. Hierzu muss über die obligatorische Option --srid die datenbankspezifische SRID (Spatial Reference ID) des gewünschten CRS festgelegt werden. In den meisten Fällen ist die SRID identisch mit dem EPSG-Code des CRS.

Die Option --crs-name ermöglicht es, einen OGC-konformen Namen für das CRS festzulegen. Der CRS-Name wird beispielsweise beim Export von Daten in die CityGML/CityJSON-Dateien geschrieben. Wird die Option weggelassen, wird standardmäßig der URN-kodierte Name urn:ogc:def:crs:EPSG::<SRID> verwendet, wobei <SRID> durch den Wert der --srid Option ersetzt wird.

Das Koordinatenreferenzsystem kann jederzeit nach dem Aufsetzen der VCDB mit der Datenbankfunktion citydb_pkg.change_schema_srid geändert werden. Weitere Informationen finden sich im Abschnitt Datenbank-Funktionen.

Changelog-Erweiterung

Es kann ausgewählt werden, ob die Changelog-Erweiterung für die neue VCDB-Instanz installiert und aktiviert werden soll. Die Changelog-Erweiterung fügt eine weitere Tabelle zum VCDB-Schema hinzu, in der Import-, Delete- und Update-Operationen an Top-Level Stadtobjekten getrackt werden. Um die Changelog-Erweiterung zu aktivieren, muss einfach nur die Option --enable-changelog gesetzt werden.

Bei aktivierter Changelog-Erweiterung können Import-, Delete- und Update-Operationen aufgrund der zusätzlichen Protokollierung länger dauern.

Ausgabe und Logging

Das folgende Beispiel zeigt die Verwendung des create Befehls.

Linux
Windows CMD

./vcdb database create \
    -H localhost \
    -d citydb \                        # Zieldatenbank
    -u citydb_user \                   # Besitzer der VCDB-Instanz
    -p mySecret \
    --db-admin-user admin_user \       # Admin-User zum Anlegen der Zieldatenbank und des Besitzers
    --db-admin-password adminSecret \
    --srid 25832 \
    --enable-changelog

vcdb database create ^
    -H localhost ^
    -d citydb ^                        # Zieldatenbank
    -u citydb_user ^                   # Besitzer der VCDB-Instanz
    -p mySecret ^
    --db-admin-user admin_user ^       # Admin-User zum Anlegen der Zieldatenbank und des Besitzers
    --db-admin-password adminSecret ^
    --srid 25832 ^
    --enable-changelog

Beim Ausführen des create Befehls werden Log-Meldungen in der Konsole ausgegeben, die den Fortschritt der Operation dokumentieren. Bei erfolgreicher Ausführung werden die Datenbankdetails der neu erstellten VCDB-Instanz auf der Konsole ausgegeben. Im Fehlerfall enthält die Log-Ausgabe eine entsprechende Fehlermeldung, die bei der Identifizierung der Fehlerursache unterstützt.

Wenn die Option --log-level auf debug gesetzt ist, enthält das Log-Protokoll zusätzlich die Ausgaben des Datenbank-Clients, der die SQL-Skripte ausführt.

Die Datenbankdetails der VCDB-Instanz können 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 database create [...] -o new-vcdb.json      # JSON in Datei schreiben
./vcdb database create [...] -o -                  # JSON auf stdout ausgeben
./vcdb database create [...] -o - > new-vcdb.json  # stdout in Datei umleiten

vcdb database create [...] -o new-vcdb.json      # JSON in Datei schreiben
vcdb database create [...] -o -                  # JSON auf stdout ausgeben
vcdb database create [...] -o - > new-vcdb.json  # stdout in Datei umleiten

Die JSON-Ausgabe enthält die Verbindungsparameter wie die Zieldatenbank und den Besitzer der VCDB-Instanz sowie weitere relevante Metdaten der Datenbank. Es wird die gleiche Struktur wie bei der Ausgabe des info Befehls genutzt.

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

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