Datenbankeinrichtung für Entwickler
Einrichtung der Datenbank "von Hand"
Dieser Ablauf hier spiegelt wieder, was das Installationsskript des Server-Paketes von iDempiere macht. Man kann also genausogut dieses nutzen. Einerseits ist es jedoch gut zu wissen, was wirklich passiert andererseits kann man so auch eine Datenbank anlegen, ohne ein Serverpaket der passenden Version zu haben (z.B. bei einer reinen Source-Installation in Eclipse).
Diese Befehle installieren die sogenannte Datenbank-Seed, d.h. die Version der Datenbank, die für das letzte stabile Release des Programms festgelegt wurde. Änderungen, die danach im Code-Baum eingeführt wurden, werden erst durch sogenannte Migrationsskripte eingespielt (s.u.).
Datenbank-Benutzer "adempiere" anlegen
sudo su - postgres psql -U postgres -c "CREATE ROLE adempiere SUPERUSER LOGIN PASSWORD 'adempiere'" logout psql -d idempiere -U adempiere -c "ALTER ROLE adempiere SET search_path TO adempiere, pg_catalog"
(Natürlich sollte man ein eigenes Passwort benutzen!)
Anmerkung: Diese Befehle gehen davon aus, das PostgreSQL lokal installiert ist. Falls nicht, benutzen Sie die Parameter "-h" (host) und ggf. "-p" (port). Außerdem kann es nötig sein, Anpassungen in der Datei pg_hba.conf vorzunehmen, um die Zugriffsrechte anzupassen. Dies sind reine PostgreSQL-Themen, die hier (bisher) nicht behandelt werden. Bitte sehen Sie in die PostgreSQL-Dokumentation.
Datenbank "idempiere" erstellen
createdb --template=template0 -E UNICODE -O adempiere -U adempiere idempiere
Datenbank-Seed ausführen
Die Datenbank-Seed enthält die gesamte Struktur der Datenbank und alle Grundeinstellungen. Man importiert sie mit:
cd org.adempiere.server-feature/data/seed/ jar xvf Adempiere_pg.jar psql -d idempiere -U adempiere -f Adempiere_pg.dmp rm ADempiere_pg.dmp
weitere Informationen
Als Basisinformation kann man auch die (nicht mehr ganz aktuelle) Seite von User:CarlosRuiz zu dem Thema lesen: http://www.globalqss.com/wiki/index.php/IDempiere/Importing_DB_Seed_Manually Insbesondere ist die Einrichtung von UUID-Unterstützung in PostgreSQL sowie die Unterteilung in verschiedene PostgreSQL-Versionen mit einem aktuellen iDempiere nicht mehr nötig (denke ich).
Migration von Änderungen
Mit sehr vielen Anpassungen an iDempiere sind auch Anpassungen an der Datenbank-Seed (also der Grundinstallation der Datenbank) verbunden. So kommt es, das man immer, wenn man eine Entwicklerversion laufen lassen will, Anpassungen an der Datenbank-Seed vornehmen muss bzw. aufmerksam darauf achten muss, das man passende Versionen zusammen benutzt.
Welche Dateien werden benutzt und wofür?
Jedesmal, wenn eine Änderung in den Sourcecode eingefügt wird, die eine Änderung in der Datenbank mit sich zieht, wird ein sogenanntes Migrationsskript hierzu erstellt (genaugenommen zwei - für PostgreSQL und für Oracle). Diese kommen in ein Verzeichnis, dessen Name im Source-Baum "migration/*-release/postgresql/" (bzw. ".../oracle/") lautet. Das "*" bezeichnet hierbei die letzte stabile Release von iDempiere. Hier sind also alle Änderungen seit dieser Release in einzelnen Dateien zusammengefasst. Die Migrationsskripte haben einen Dateinamen, der mit ihrem Datum beginnt, so das es immer sicher ist, diese in alphabetischer Reihenfolge einzuspielen.
Sobald eine neue offizielle Release der Software erstellt wird, wird eine leere Datenbank genommen, der bisherige (alte) Seed wird eingespielt, dann werden alle Migrationsskripte einzeln in alphabetischer Reihenfolge ausgeführt. Sodann wird von der neuen Datenbank ein Backup gemacht und dieses als neues Seed in den Quellbaum eingestellt. Danach wird das bisherige Migrationsverzeichnis anhand der Namen der neuen Version umgenannt und ein neues Migrationsskript-Verzeichnis "<neueVersion>-release" angelegt.
Die Datenbank-Seed findet sich im Source-Baum unter org.adempiere.server-feature/data/seed/Adempiere_pg.jar (bzw. ohne "_pg" für Oracle).
Jedes Miggrationsskript schreibt einen Eintrag in die Datenbank in die Tabelle ad_migration, anhand dessen man erkennen kann, das es eingespielt wurde. Damit kann man sehen, wie weit eine Datenbank migriert worden ist (um nichts versehentlich doppelt auszuführen).
Da es einige Tabellen in iDempiere gibt, die normalerweise automatisch mitgepflegt werden, wenn Änderungen vorgenommen werden (z.B. eine Liste der aktuellen Datensatznummern und ähnliches), sollte man immer nach dem Einspielen eines Updates in die Datenbank die Skripte in /migration/process_post_migration/ ausführen. Sie aktualisieren alles, was die Migrationsskripte u.U. nicht erfasst haben.
Was tun bei einem Upgrade (Migration)
Ich habe nun ein Weilchen an meinem iDempiere herumgespielt und bemerke, das sich die Welt weitergedreht hat. Ich möchte nun also meinen Entwicklercode und die dazugehörige Datenbank aktualisieren. Wie gehe ich vor?
cd /pfad/zu/meinem/workspace hg pull https://bitbucket.org/idempiere/idempiere hg update -rtip
Anmerkung: Ich empfehle dringend, darüber nachzudenken, was mit eigenen Änderungen geschieht, die sich bereits im Repository befinden. Sprich: Entweder sind die eigenen Änderungen bereits alle im Haupt-Repository eingefügt (beste Lösung) oder man hat einen eigenen Branch für seine Anpassungen definiert (auch gute Lösung) oder man erzeugt durch das update einen zweiten Head in seinem Repository, den man dann anschließend noch ggf. mergen muss (nicht Teil dieses Artikels).
Auf jeden Fall geht's jetzt weiter mit der eigentlichen Datenbank-Anpassung:
cd migration/*-release/postgresql psql -h localhost -U adempiere -d idempiere -qAt -c 'select name from AD_Migrationscript ORDER BY name;' >/tmp/migrations_db ls *.sql >/tmp/migrations_dir cat `comm -13 /tmp/migrations_db /tmp/migrations_dir` | psql -h localhost -U adempiere -d idempiere cd ../../processes_post_migration/postgresql/ cat `ls *.sql` | psql -h localhost -U adempiere -d idempiere
Jetzt ist die Datenbank auf den neuen Stand angepasst. Nun kann man iDempiere aus Eclipse heraus starten oder Installationspakete erzeugen.
Upgrade aus der IDE
In Installation_der_Entwicklungsumgebung#DB_Migration habe ich den Fall beschrieben, bei dem eine neue iDempiere-Software erstellt wurde und die DB ist noch zu migrieren. Ich kann die Migration (ca 50 sql-scripte)
- per psql, db-"konsole" (Doku zu V9.1 hier)
- via pgAdmin III, postgres GUI-Schnittstelle
- oder direkt aus der IDE, eclipse-DB Development (Indigo)
ausführen. Die dritte Variante beschreibe ich hier.
Voraussetzung für eclispe (helios und indigo) ist
- DTP 1.9, Data Tools Platform : http://www.eclipse.org/datatools/
In der Perspective "Database Development"
Window > Open Perspective > Other... > Database Development
eine Verbindung zur Datanbank herstellen. Dazu muß gegebenenfalls der JDBC-Treiber der Datenbank (in meinem Fall postgresql-9.1-901.jdbc4.jar) installiert werden. Die Treiber werden nicht im DTP dabei, weil sie nicht von eclipse sondern vom DBMS-Hersteller geliefert werden.
Nachdem die Verbindung zu DB hergestellt ist kann man wieder zurück in die ursrüngliche Perspective (Plug-in Development oder Java, je nach Gusto). Das erste sql-script-file öffnen, das man ausführen muß, z.B.:
/migration/i1.0a-release/postgresql/201211091228_IDEMPIERE-316.sql
Mit Ctrl-Alt-X (Execute All) script ausführen:
In der "SQL Result"-View sieht man das Ergebnis und den Status des Updates. Wenn alle scripte abgearbeitet sind, ist die Datenbank und die neu erstellte iDempiere-Applikation synchronisiert.
