↓ Zum Hauptinhalt springen
credativ-pg-migrator
credativ-pg-migrator

Dokumentation

Inhaltsverzeichnis

Diese Seite gibt Ihnen einen Überblick zur ersten Orientierung. Die vollständige, gepflegte Dokumentation liegt im Repository — der User Guide beschreibt jeden Connector, jede Option und jede Einschränkung im Detail.

Funktionsweise
#

credativ-pg-migrator ist ein Offline-Migrationswerkzeug. Es verbindet sich mit der Quelldatenbank, analysiert das Datenmodell, erzeugt PostgreSQL-kompatible Strukturen und schreibt diese in die Zielinstanz. Es ist dafür ausgelegt, während eines Wartungsfensters bzw. Read-only-Fensters auf der Quelle zu laufen, und nicht als Lösung für eine Live-Replikation.

In der Praxis wird die Migrationsgeschwindigkeit durch Hardware und Netzanbindung begrenzt — die Erfahrung zeigt, dass in der Regel der Server der Quelldatenbank der Engpass ist und nicht der Migrator.

Komponenten
#

KomponenteAufgabe
ParserLiest die YAML-Konfigurationsdatei und die Kommandozeilenargumente.
PlannerLiest Metadaten und Objektdefinitionen aus der Quelle und überführt sie in ihre PostgreSQL-Entsprechungen.
OrchestratorFührt die Migrationsschritte aus und koordiniert die parallelen Worker.
WorkerFühren den Datentransfer und das Anlegen der Objekte parallel aus.
Architektur von credativ-pg-migrator

Die drei Datenbanken
#

An einer Migration sind immer drei logische Datenbanken beteiligt:

  • Quelldatenbank — jedes unterstützte System, angebunden über ODBC, JDBC oder einen nativen Python-Treiber. Es muss sich dabei nicht um einen Server handeln: Eine SQLite-Quelle ist eine einfache lokale Datei, und eine DB2-z/OS-Quelle kann aus einer Sammlung von Offline-DDL- und CSV-Dateien bestehen.
  • Zieldatenbank — die PostgreSQL-Instanz, in der das migrierte Schema und die Daten angelegt werden. PostgreSQL ist das einzige unterstützte Ziel.
  • Migrationsdatenbank — eine PostgreSQL-Datenbank, die das Migrationsprotokoll aufnimmt: jedes migrierte Objekt mit seinem Quellcode, dem erzeugten PostgreSQL-Code sowie einer Erfolgs- oder Fehlermarkierung mit Zeitstempeln. Üblicherweise ist dies die Zieldatenbank selbst, es kann aber auch eine separate Datenbank sein.

Installation
#

Python-Paket
#

python3 -m venv migrator_venv
. ./migrator_venv/bin/activate
pip install credativ-pg-migrator

Das Paket ist auf PyPI verfügbar: pypi.org/project/credativ-pg-migrator.

Debian und Ubuntu
#

credativ-pg-migrator ist Bestandteil des PostgreSQL-Community-Repositories apt.postgresql.org. Wie Sie dieses einbinden, beschreibt die PostgreSQL-APT-Wikiseite.

Je nach Quelldatenbank benötigen Sie zusätzlich den passenden ODBC- oder JDBC-Treiber. Die Ausnahme ist SQLite — hier ist überhaupt keine Treiberinstallation erforderlich.

Konfiguration
#

Der Migrator wird über eine einzige YAML-Datei gesteuert. Diese beschreibt die Quelle, das Ziel, die Migrationsdatenbank, welche Objekte migriert werden sollen und wie sie zu konvertieren sind.

Am schnellsten kommen Sie zum Ziel, wenn Sie das fertige Beispiel für Ihr Quellsystem aus docs/configs/ kopieren und jede mit >>> ADJUST markierte Zeile anpassen.

Eine Konfigurationsdatei umfasst typischerweise:

  • Einstellungen der Quelle — Systemtyp, Host, Port, Datenbank, Zugangsdaten, Art der Anbindung (odbc, jdbc, ddl oder nativ) sowie Angaben zu Treiber, JAR-Datei bzw. DSN.
  • Einstellungen des Ziels — PostgreSQL-Verbindungsdaten und das Standardschema für die migrierten Objekte.
  • Einstellungen der Migrationsdatenbank — wo die Protokolltabellen angelegt werden.
  • Objektauswahl — welche Schemata migriert werden sollen, Einschluss- und Ausschlusslisten für Tabellen, Views, Sequenzen und Routinen.
  • Optionen für den Datentransfer — WHERE-Filter je Tabelle, Batch-Größen, Konfliktbehandlung und der Umgang mit Fremdschlüsseln während des Ladevorgangs.
  • Abbildung von Datentypen und Default-Werten — Regeln, die Datentypen der Quelle und herstellerspezifische Default-Ausdrücke auf PostgreSQL-Entsprechungen abbilden.
config_all_options_reference.yaml dokumentiert sämtliche vorhandenen Optionen und ist die maßgebliche Referenz — aber keine Vorlage. Die Datei führt sich gegenseitig ausschließende Optionen nebeneinander auf und lässt sich daher nicht unverändert als Konfigurationsdatei verwenden.

Eine Migration durchführen
#

credativ-pg-migrator \
  --config=./my_migration.yaml \
  --log-file=./my_migration_$(date +%Y%m%d).log \
  --log-level=INFO

Die Protokollierung erfolgt sowohl auf der Konsole als auch in der Logdatei. Es stehen zwei Detailstufen zur Verfügung, INFO und DEBUG; im Fehlerfall wird eine ausführliche Meldung ausgegeben. Parallel dazu werden umfangreiche Informationen in die Migrationsdatenbank geschrieben.

Ein typisches Migrationsprojekt
#

  1. PostgreSQL vorbereiten. Richten Sie die Zielinstanz ein und entscheiden Sie, ob die Migrationsdatenbank dieselbe Datenbank oder eine separate ist.
  2. Anbindung vorbereiten. Installieren Sie die benötigten JDBC-, ODBC- oder nativen Treiber und prüfen Sie die Verbindung unabhängig davon — etwa mit isql für ODBC —, bevor Sie den Migrator einsetzen.
  3. Konfiguration erstellen. Beginnen Sie mit dem Beispiel für Ihr Quellsystem, tragen Sie die Verbindungsdaten ein, wählen Sie Schemata und Tabellen aus und ergänzen Sie die benötigten Typ- und Default-Abbildungen sowie Datenfilter.
  4. Testmigration durchführen gegen ein Ziel außerhalb der Produktion mit der Stufe INFO. Prüfen Sie die Logausgabe, die Protokolltabellen in der Migrationsdatenbank sowie das entstandene Schema und die Daten.
  5. Anpassen und erneut ausführen. Verfeinern Sie Abbildungen, Filter und Objektauswahl, bis das Ergebnis Ihren Erwartungen entspricht.
  6. Produktivmigration durchführen während eines Wartungsfensters bzw. Read-only-Fensters auf der Quelle, das Ergebnis validieren und anschließend die Anwendungen auf PostgreSQL umstellen.

Die Migrationsdatenbank
#

Das Migrationsprotokoll ist eine der zentralen Stärken des Werkzeugs. Für jedes migrierte Objekt hält es die Namen in Quelle und Ziel fest, das zum Anlegen des Zielobjekts verwendete SQL, den Status (erfolgreich, übersprungen, Fehler) sowie Zeitstempel — für Tabellen, Indizes, Fremdschlüssel, Views, Sequenzen und für Funktionen, Prozeduren und Trigger einschließlich ihres ursprünglichen Quellcodes und des erzeugten PostgreSQL-Codes.

Das ermöglicht Ihnen:

  • exakt nachzuvollziehen, was auf welche Weise migriert wurde;
  • den Quellcode mit dem erzeugten PL/pgSQL zu vergleichen — der praktikable Weg, die Best-Effort-Konvertierungen zu prüfen, bevor Sie ihnen vertrauen;
  • einzelne Objekte erneut zu migrieren oder manuell zu korrigieren, ohne die gesamte Migration zu wiederholen.

Behandeln Sie die Migrationsdatenbank als Metadaten mit Lesezugriff: Fragen Sie sie beliebig ab, ändern Sie ihre Tabellen aber nicht direkt.

Validierung nach der Migration
#

Der Migrator bringt eine Validierungs-Engine mit, die das Ziel unabhängig von der Migration selbst gegen die Quelle prüft:

  • Zeilenanzahlen und Prüfsummen über die gesamte Tabelle für jede Quelle mit einer Live-Verbindung.
  • Hashwerte zufällig ausgewählter Zeilen und LOB-Bytegrößen (derzeit für Quellen mit Oracle, PostgreSQL und SQLite).
  • Struktureller Vergleich der Anzahl von Spalten, Indizes und Constraints, festgehalten in den Protokolltabellen validation_tables, validation_indexes und validation_constraints.

Die Ergebnisse werden als Zusammenfassung in Markdown mit gegenübergestellten Tabellen ausgegeben; jede Abweichung markiert die Validierung der betroffenen Tabelle als fehlgeschlagen.

Weiterführende Informationen
#