Datenbank aufsetzen

Für die Einrichtung eine Bare-Metal VC Database (VCDB) Instanz wird die Verwendung der Installationsskripte empfohlen, die als separates VCDB Download-Paket bereitgestellt werden. Diese Skripte sind auch in jeder vcdb-tool Distribution enthalten. Alternativ kann Docker für eine einfache Einrichtung und Bereitstellung einer VCDB-Instanz genutzt werden.

Schritte zum Aufsetzen einer VCDB

Schritt 1: Eine leere PostgreSQL-Datenbank erstellen

Der erste Schritt ist die Erstellung einer neuen, leeren Datenbank auf dem PostgreSQL Datenbankserver. Dazu muss ein Superuser oder ein Datenbankbenutzer mit der CREATEDB Berechtigung verwendet werden. Obwohl nicht erforderlich, wird empfohlen, einen dedizierten Benutzer auszuwählen oder zu erstellen, der Eigentümer der neuen Datenbank ist und auch für die Ausführung der VCDB Setup-Skripte in den nachfolgenden Schritten verwendet werden sollte.

Der folgende Befehl zeigt, wie eine neue Datenbank für den Benutzer citydb_user erstellt wird.

CREATE DATABASE citydb_v5 OWNER citydb_user;
Der Befehl kann mit dem PostgreSQL Kommandozeilen-Client psql oder jedem anderen SQL-Werkzeug ausgeführt werden. Beispielsweise bietet die Software pgAdmin eine benutzerfreundliche, grafische Oberfläche zur Verwaltung von PostgreSQL-Datenbanken. Weitere Informationen finden sich in der Dokumentation der jeweiligen Software.

Schritt 2: Die PostGIS-Erweiterung hinzufügen

Die VC Database erfordert das Hinzufügen der PostGIS-Erweiterung zur Datenbank. Dies kann nur von einem Superuser durchgeführt werden. Der folgende Befehl kann dazu verwendet werden, um die PostGIS-Erweiterung zu installieren:

CREATE EXTENSION postgis;
Optional

Um weitergehende räumliche 3D-Operationen wie Extrusion, Volumenberechnung oder Vereinigung/Schnittmenge/Differenz von Volumengeometrien zu ermöglichen, kann zusätzlich die postgis_sfcgal-Erweiterung installiert werden:

CREATE EXTENSION postgis_sfcgal;

Schritt 3: Das connection-details Skript bearbeiten

Nach dem Aufsetzen der PostgreSQL-Datenbank können nun die VCDB Installationsskripte verwendet werden. Die Skripte liegen im Ordner vcdb/postgresql/shell-scripts unterhalb des Verzeichnisses, in dem das VCDB-Softwarepaket entpackt wurde. Alternativ befindet sich ein entsprechender Ordner auch im Installationsverzeichnis von vcdb-tool. Bitte wechseln Sie abhängig vom Betriebssystem, auf welchem die Skripte ausgeführt werden sollen, in den Unterordner unix oder windows.

Innerhalb dieses Ordners befindet sich die Datei connection-details.[sh|bat]. Öffnen Sie diese Datei mit einem Texteditor Ihrer Wahl und tragen Sie dort die Verbindungsdetails zur angelegten Datenbank zusammen mit dem vollständigen Pfad zur ausführbaren psql-Datei ein. Wie oben erwähnt, wird empfohlen, den Benutzer, dem die Datenbank gehört, als PGUSER im Skript anzugeben.

Das nachfolgende Beispiel zeigt die erforderlichen Informationen, die in connection-details eingetragen werden müssen.

  • Linux

  • Windows CMD

#!/bin/bash
# Provide your database details here ----------------
export PGBIN=/var/lib/postgresql/[version]/bin
export PGHOST=localhost
export PGPORT=5432
export CITYDB=citydb_v5
export PGUSER=citydb_user
#----------------------------------------------------
# Provide your database details here ----------------
set PGBIN=C:\Program Files\PostgreSQL\[version]\bin
set PGHOST=localhost
set PGPORT=5432
set CITYDB=citydb_v5
set PGUSER=citydb_user
#----------------------------------------------------
Wenn der Pfad zur ausführbaren psql-Datei bereits in der PATH Umgebungsvariable enthalten ist, kann die Zeile zum Setzen der PGBIN-Variable auch auskommentiert oder gelöscht werden.

Schritt 4: Das create-db Skript ausführen

Sobald die Verbindungsdetails in der connection-details Datei eingetragen wurden, wird der Setup-Prozess durch das Ausführen des create-db.[sh|bat] Skripts gestartet. Das Skript kann entweder durch einen Doppelklick oder über den Aufruf in einer Shell-Umgebung ausgeführt werden. In UNIX/Linux-Umgebungen müssen möglicherweise zuerst die entsprechenden Dateiberechtigungen gesetzt werden, um das Skript ausführbar zu machen.

  • Linux

  • Windows CMD

chmod u+x create-db.sh
./create-db.sh
create-db.bat

Es ist auch möglich, eine andere connection-details Datei aus einem anderen Ordner zu verwenden:

  • Linux

  • Windows CMD

./create-db.sh /path/to/connection-details.sh
create-db.bat C:\path\to\connection-details.bat

Nach dem Start des Skripts wird eine Willkommensnachricht zusammen mit Nutzungshinweisen auf der Konsole ausgegeben. Das Skript fordert den Benutzer zur Eingabe mehrerer wesentlicher Parameter auf, die für die Einrichtung der VCDB-Instanz erforderlich sind. Die Details zu diesen Benutzereingaben werden in den folgenden Schritten erklärt.

Schritt 5: Das Koordinatenreferenzsystem definieren

Zunächst muss das Koordinatenreferenzsystems (CRS) definiert werden, das für die VCDB-Instanz verwendet werden soll. Hierzu muss einfach die PostGIS-spezifische SRID (Spatial Reference ID) des CRS eingeben werden. In den meisten Fällen ist die SRID identisch mit dem EPSG-Code des CRS. Insgesamt müssen in diesem Schritt drei Parameter angegeben werden:

  • Die SRID, die für Geometrien in der Datenbank verwendet werden soll: Es kann nur genau eine SRID für die VCDB-Instanz verwendet werden.

  • Der EPSG-Code des Höhenbezugssystems: Die Angabe des Höhenbezugssystems ist ein Metadatum und beeinflusst nicht die Speicherung von Geometrien in der Datenbank. Wenn die obige SRID bereits ein echtes 3D-CRS referenziert oder wenn das Höhenbezugssystem unbekannt ist, kann an dieser Stelle einfach "0" eingegeben werden (gleichbedeutend mit "nicht bekannt"). Das ist auch der Standardwert.

  • Der OGC-konforme Name des CRS: Der CRS-Name wird beispielsweise beim Export von Daten in die CityGML/CityJSON-Dateien geschrieben. Das create-db Skript schlägt basierend auf den vorigen Angaben einen URN-kodierten CRS-Namen vor, der entsprechenden OGC-Empfehlungen folgt. Drücken Sie einfach Enter, um den Vorschlag zu übernehmen.

    urn:ogc:def:crs,crs:EPSG::<SRID>[,crs:EPSG::<HEIGHT_EPSG>]
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.

Schritt 6: Changelog-Erweiterung installieren

Es kann ausgewählt werden, ob die Changelog-Erweiterung für die VCDB-Instanz installiert 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. Jeder Changelog-Eintrag stellt Metadaten über das betroffene Stadtobjekt (Identifier, Envelope, etc.), den ausführenden Datenbankbenutzer, den Aktualisierungsgrund und die Art der Transaktion bereit. Im Hintergrund werden Datenbank-Trigger genutzt, um die Changelog-Tabelle automatisch zu befüllen. Dementsprechend können Import-, Delete- und Update-Operationen länger dauern, wenn die Changelog-Erweiterung verwendet wird.

Geben Sie yes oder no ein, um zu entscheiden, ob die Changelog-Erweiterung installiert werden soll. Der Standardwert ist no, was durch einfaches Drücken von Enter bestätigt werden kann.

Die Changelog-Erweiterung kann auch jederzeit nach dem Aufsetzen der VCDB mit den Shell-Skripten create-changelog und drop-changelog installiert und entfernt werden.

Schritt 7: Die Installation starten

Abschließend muss das Passwort für den Datenbankbenutzer eingegeben werden, der im connection-details Skript angegeben wurde. Danach beginnt der Setup-Prozess und Log-Meldungen auf der Konsole informieren über den Installationsfortschritt.

Der Setup-Prozess wird im Fehlerfall sofort beendet. Mögliche Fehlerursachen sind:

  • Der Benutzer, der create-db ausführt, ist weder ein Superuser noch der Eigentümer der angegebenen Datenbank (oder hat nicht die Berechtigungen, Objekte in dieser Datenbank zu erstellen).

  • Die PostGIS-Erweiterung wurde nicht installiert.

  • Die angegebene SRID wird nicht unterstützt.

  • Teile der VCDB existieren bereits aufgrund eines vorherigen Installationsvorgangs. Um dies zu verhindern, ist sicherzustellen, dass die Schemata citydb, citydb_pkg und vcdb_pkg vor dem Start des Setup-Prozesses nicht in der Datenbank existieren.

Wenn keine Fehlermeldung angezeigt wird, wurde die Installation erfolgreich abgeschlossen. Die Abbildung unten zeigt eine Zusammenfassung der erforderlichen Benutzereingaben für das create-db Skript.

image createDBScript
Figure 1. Beispiel-Benutzereingabe für das create-db Skript.
Zusätzlich zu den connection-details und create-db Shell-Skripten für die Einrichtung einer VCDB-Instanz enthält das VCDB-Paket weitere Shell- und SQL-Skripte für Aufgaben wie das Löschen einer VCDB-Instanz, die Erstellung zusätzlicher Datenbank-Schemata und das Erteilen oder Entziehen von Zugriffsberechtigungen. Eine vollständige Dokumentation dieser Datenbankskripte ist hier verfügbar.

Template-Datenbanken zum Aufsetzen einer VCDB verwenden

In PostgreSQL sind Template-Datenbanken vorkonfigurierte Datenbanken, die als Basis für die Erstellung neuer Datenbanken dienen. Die Verwendung einer Template-Datenbank bei der Datenbankerstellung ist eine gängige Praxis. Die neue Datenbank wird im Wesentlichen als Kopie einer der Template-Datenbanken erstellt, mit einigen Änderungen (wie dem Datenbanknamen). Diese Template-Datenbanken ermöglichen eine schnelle Datenbankerstellung durch Kopieren einer vorhandenen Struktur, eines Schemas und sogar von Daten.

Auch eine VCDB-Instanz kann als Template-Datenbank genutzt werden. Jedoch muss beachtet werden, dass der search_path nicht automatisch von der Template-Datenbank zur neuen VCDB-Instanz kopiert wird. Ein korrekter Suchpfad ist jedoch entscheidend für den Zugriff auf Daten und Datenbankfunktionen in den Schemata citydb, citydb_pkg und vcdb_pkg. Daher muss der Suchpfad in der neuen VCDB-Instanz manuell gesetzt werden:

ALTER DATABASE new_citydb_v5 SET search_path TO citydb, citydb_pkg, vcdb_pkg, public;
Wenn die VCDB-Template weitere Schemata enthält, muss sichergestellt werden, dass alle zum search_path hinzugefügt werden. Der Suchpfad wird erst beim nächsten Login aktualisiert, nicht innerhalb derselben Sitzung.

Aktualisierung einer VCDB v5 auf die neueste Version

Wenn Sie bereits eine VCDB v5 Instanz installiert und in Betrieb haben und diese auf die neueste Version aktualisieren möchten, anstatt eine neue Instanz aufzusetzen, folgen Sie bitte dieser Anleitung.