SQLcl Project Orchestration Made Easy Part2
Databaseguy, Oracle Apex Lover
Anwender-Dokumentation für SQLCL Deploy — ein Web-Tool, das SQLcl-Project- Deployments für Oracle-Datenbanken organisiert. Anstelle von einzelnen SQL-Skripten und manuellem Schritt-für-Schritt arbeitest du mit Pipelines, die du im Browser startest, beobachtest und kontrollierst.
Diese Doku führt dich durch die typischen Aufgaben — Release vorbereiten, deployen, Probleme beheben, Konfiguration pflegen.
Inhalt
1. Was du im Tool siehst
Nach dem Login (oder direktem Aufruf der URL — keine Auth in der internen Version) erwartet dich ein dreigeteiltes Layout:
Links — Sidebar mit:
Neuen Run starten: Pipeline-Auswahl + Eingabefelder, "Run anlegen"-Button
Runs: Liste der bisherigen Runs, neueste oben
Mitte (groß) — wenn ein Run ausgewählt ist:
Header mit Pipeline-Name, Status, "Abbrechen" + "Log herunterladen"
Liste aller Stages mit Status-Badges (pending / running / blocked / done / failed / skipped)
Live-Log
Oben in der Navbar:
Pipelines / Features / Docs / Admin (klickbar)
🌿 Branch-Indikator (zeigt auf welchem Branch dein ERP-Repo gerade steht)
🔌 Connection-Indikator (welche DB-Connection aktiv eine Stage benutzt)
"verbunden" — grünes Health-Badge
Splitter zwischen Stages und Log — ziehbar. Doppelklick zum Reset. Log auch komplett wegklappbar (✕ in der Log-Header-Leiste, "Log ›"-Button oben rechts holt's zurück).
2. Einen Release-Kandidat erstellen
Pipeline: Release-Kandidat erstellen (Gruppe: Release)
Was passiert: Aus dem aktuellen main-Branch im ERP-Repo wird ein neuer release-candidat_<version>-Branch erzeugt. Die Pipeline geht durch ~25 Schritte: Sessions checken, Code-Freeze bestätigen, Schemas kompilieren, DDL-Export (parallel, mehrere Worker), APEX-Apps exportieren, Project Staging, DDL-Inspector, Git-Commit, Artifact erstellen.
Schritt-für-Schritt
Pipeline auswählen im Dropdown links:
Release-Kandidat erstellen (candidat).Eingaben füllen:
Arbeitsverzeichnis: ist vorausgefüllt (kommt aus dem Admin-Setup).
Versionsnummer: Default kommt aus dem aktuellen Branch-Namen oder deinem letzten Run. Format
0.6.2(drei oder vier Segmente).Last Deploy Date (optional): Filter für DDL-Export, der nur Änderungen seit diesem Datum exportiert. Lass leer für alle.
"Run anlegen" klicken → Run erscheint in der Sidebar mit Status
pending. Klick auf den Run → Stage-Liste rechts.Start-Button im Run-Header klicken → Pipeline läuft los.
Was du dann tust
Die Pipeline blockt mehrfach für deine Bestätigung:
"Code-Freeze bestätigen" — gibt dir die Chance, mit den Entwicklern Rücksprache zu halten. Klick auf ✓ Bestätigen wenn alle informiert sind.
"Project Stage" läuft durch (kann 1–5 Minuten dauern, abhängig von der Anzahl der Änderungen).
"Review der gestageten Dateien" — du kannst alle SQL-Files unter
dist/releases/next/changes/<branch>/durchklicken, ansehen und editieren. Wenn du was änderst, wird ein.review-bak-Backup angelegt und der Originalpfad überschrieben. Nicht-bearbeitete Files bleiben unverändert. Klick auf ✓ Bestätigen wenn fertig."object_grants — failOnError:false setzen" — patcht automatisch alle Liquibase-Changesets unter
**/object_grants/so, dass sie bei einem Fehler weiterlaufen statt den ganzen Deploy zu stoppen. Läuft durch ohne deine Bestätigung."DDL-Inspector" — siehe Kapitel 6.
"APEX-Stage committen" — git commit der gestageten Files. Läuft durch.
"Project Release erzeugen" und "Artifact erstellen" — produzieren die
.zip-Datei unterartifact/zodis_erp-candidat_<version>.zip.
Am Ende ist der Run mit Status done markiert, der Candidat-Branch ist gepusht, und das Artifact liegt bereit für den Deploy.
3. Auf TESTMIG deployen und prüfen
Pipeline: Testmig Re-Run (Candidat verifizieren) (Gruppe: Full Deploy)
Was passiert: Nimmt das .zip-Artifact aus dem Candidat-Schritt, baut es als .test.zip neu (mit anderem Suffix für Test-Marker), deployt auf TESTMIG, kopiert KON-Stammdaten und ADM-Params per DBLink von DEV nach TESTMIG, und blockt am Ende für deine Verifikation.
Vorbedingungen
Candidat-Pipeline ist mit
donedurchgelaufen.Workdir-Branch steht weiterhin auf
release-candidat_<version>.
Ablauf
Pipeline auswählen, Version eingeben (Default greift), "Run anlegen".
"Mit Testmig-Deploy fortfahren?" bestätigen.
"Test-Artifact erzeugen" — baut
.test.zip(1–3 Min)."DB-Link Synonyme installieren" — Setup vor dem Deploy.
"Deploy .test-Artifact auf TESTMIG" — das ist der eigentliche Liquibase-Run. Kann 5–60 Minuten dauern. Live-Log zeigt:
Synonym X created/Table Y alteredfür jedes ChangesetUPDATE SUMMARYam Ende: Run-Zähler, Filtered-out-Zähler, Total
"Übersicht — manuelle File-Änderungen" — zeigt alle Files die du im Review-Schritt geändert hast plus den git-Status. Hilfreich um zu sehen ob du Edits hast, die du in den nächsten Test/Prod-Deploys nochmal brauchst.
"KON-Stammdaten von DEV nachziehen" und "ADM-Params von DEV nachziehen" — kopieren neue Stammdaten via DBLink.
"Candidat-Verifikation auf TESTMIG" — du wirst gefragt ob's funktioniert hat. Wenn ja: Pipeline ist fertig, weiter mit Kapitel 4. Wenn nein: ✗ Ablehnen klicken, Probleme analysieren, ggf.
cancel-candidat-Pipeline.
4. Auf TEST und PROD ausrollen
Wenn TESTMIG geprüft ist:
Release finalisieren (nach erfolgreichem Testmig)(Gruppe: Release) Pipeline. Merged den Candidat-Branch inmain, taggt das Release, pusht, und erstellt das finale Production-Artifact.zip(ohne.test-Suffix).Deployment auf TEST(Gruppe: Full Deploy). Inputs: Workdir + Version. Pipeline blockt vor dem Deploy für deine Bestätigung, deployt, läuft alle Post-Deploy-Schritte durch (Changelog-Check, sync-tab-map, post-deploy-Features für adm/erp, KON-Stammdaten, ADM-Params, APEX-Automations-Enable, invalid-objects prüfen, bump-adm-version).Deployment auf PROD (⚠ mit Downtime!)(Gruppe: Full Deploy). Wie TEST, aber mit App-Status-Toggles (1000/1300/1400 vor dem Deploy auf UNAVAILABLE, danach auf AVAILABLE_W_EDIT_LINK), mehreren Approval-Gates und längeren Timeouts. PROD-Connection (das letzte Approval-Modal warnt explizit).
APEX-Only Deploy
Wenn du nur APEX-Apps deployen willst (ohne DB-Schema-Änderungen), gibt es die Gruppe APEX-Only Deploy mit drei Pipelines: …testmig, …test, …prod. Jede installiert die Apps 1000/1300/1400 aus den SQLcl-Project APEX-Exports und enabled die Automations.
5. Wenn ein Deploy fehlschlägt
Liquibase- und SQLcl-Fehler sind verbos. Das Tool extrahiert für dich:
Im Stage-Fehler-Block links siehst du:
Stage fehlgeschlagen:
SQLcl failed (exit=2, oracleError=true)
Ursache: ORA-24015: cannot create QUEUE_TABLE, QUEUE_PAYLOAD_TYPE
ZODIS_DDS_Q."ECA_MSG_Q_T" does not exist
Datei: release-candidat_0.6.2/zodis_dds_q/aq_queue_tables/t_eca_qt.sql
Plus eine Reihe von Buttons:
📄 Errorfile — öffnet einen Editor mit dem Inhalt der gescheiterten SQL-Datei. Du kannst editieren und speichern. Beim Speichern wird ein
.workfile-bak-Backup angelegt.↻ Retry — die gleiche Stage nochmal ausführen. Sinnvoll wenn du die Datei nicht ändern musstest (z.B. nach einer transienten Netzwerk-Störung) oder wenn der Fix in der DB selbst gemacht wurde.
↻ Re-Build & Retry — nur sichtbar wenn die Pipeline-YAML eine
retryFrom:-Annotation hat (Standard beideploy-testmig-test). Spult die Pipeline zurück zu einer früheren Stage (typisch:gen-test-artifact) und führt von dort an alles neu aus. Brauchst du, wenn du eine SQL-Datei geändert hast und das Artifact deshalb neu gebaut werden muss.⤳ Trotzdem weitermachen — überspringt diese Stage und macht mit der nächsten weiter. Stage-Status wird
skipped.✗ Run abbrechen — Run endet mit Status
failed. Optionalem Grund.
Im Log wird der Fehler-Kontext extra hervorgehoben:
[deploy] ───── Fehler-Kontext aus dem Output ─────
Running Changeset: release-candidat_0.6.2/zodis_dds_q/aq_queue_tables/t_eca_qt.sql
Migration failed, error reported:
begin
*
ERROR at line 1:
ORA-24015: cannot create QUEUE_TABLE, QUEUE_PAYLOAD_TYPE ZODIS_DDS_Q."ECA_MSG_Q_T" does not exist
...
[deploy] ───────────────────────────────────────────
[deploy] 76 Java-Stacktrace-Zeile(n) unterdrückt
[stage] Fehler: SQLcl failed (exit=2, oracleError=true)
Java-Stacktraces (at oracle.dbtools…, at liquibase…) werden automatisch ausgeblendet — du siehst nur die relevanten ORA-/SP2-/PLS- Codes plus die Caused by:-Kette.
Workflow bei Errorfile-Fix
Klick auf 📄 Errorfile → Editor öffnet sich unten in der Fehler-Box.
Datei ansehen, bearbeiten, 💾 Speichern.
↻ Re-Build & Retry klicken → Bestätigungs-Dialog, Log wird geleert, Pipeline läuft vom Artifact-Build-Schritt an neu.
6. Der DDL-Inspector
Der DDL-Inspector läuft in der candidat-Pipeline nach dem project stage-Schritt. Er scannt alle SQL-Files unter dist/releases/next/changes/<branch>/ auf drei Problemklassen:
Auskommentierte DROP-Statements
SQLcl-Project markiert risky DDLs auskommentiert:
/*
Uncomment drop statement to remove this table
DROP TABLE "FOO";
*/
Der Inspector zeigt jedes vorkommen mit Pfad, Zeile und Statement. Du hast zwei Buttons pro Treffer:
✓ Aktivieren — der DROP wird auskommentiert und an den Anfang der Datei verschoben (nach dem Liquibase-Header). Damit er VOR allen anderen Statements der Datei läuft.
📝 Datei öffnen — Editor mit dem ganzen File-Inhalt für manuelle Edits.
Aktivierte DROPs werden zusätzlich in <workdir>/activated_ddls_<release>.sql zur Übersicht gesammelt (chronologisch, mit Datei-Kontext).
NO FLASHBACK ARCHIVE
alter table xyz no flashback archive; ist auf den meisten DBs ein no-go weil's Flashback aushebelt. Der Inspector zeigt jedes Vorkommen. Apply wickelt das Statement in /* ... */ Block-Kommentare ein.
Fehlende Sequences
Wenn ein CREATE TABLE ein <schema>.<seq>.NEXTVAL in einem Column- Default verwendet und im selben File kein CREATE SEQUENCE davor steht, wird das angezeigt. Apply fügt ein CREATE SEQUENCE vor dem CREATE TABLE ein.
Hinweis: die Sequence-Erkennung ist Best-Effort. Multi-Zeilen- Column-Definitionen oder ungewöhnliche Schreibweisen können übersehen werden. Bei einem ORA-02289 zur Deploy-Zeit greift dann der reaktive Fix-Flow (📄 Errorfile + manuelles Hinzufügen).
Ablauf
DDL-Inspector blockt mit Liste aller Treffer.
Pro Treffer entscheidest du: aktivieren, datei öffnen, oder skippen.
Nicht-angeklickte Treffer bleiben so wie sie sind.
✓ Bestätigen → Pipeline läuft weiter.
7. Cloning und Migration
Diese Pipelines sind getrennt vom Release-Flow — sie rüsten die DBs auf.
Prepare ZDB
Gruppe: Prepare ZDB
Zwei Pipelines (zdb-prepare-devb, zdb-prepare-testb) bereiten die ZDB-Quell-Datenbanken (DEVB und TSTB) auf. Aktuell als Placeholder — das Build-SQL ist noch nicht im Tool nachgebaut.
Clone
Gruppe: Clone
Fünf Pipelines die eine Ziel-PDB komplett neu aus einer Quelle aufbauen:
| Pipeline | Quelle | Ziel |
|---|---|---|
clone-dev-to-testmig |
DEV (zodd01) | TESTMIG (zodtmig) |
clone-dev-to-test |
DEV | TEST (zodt01) |
clone-test-to-testmig |
TEST | TESTMIG |
clone-prod-to-test |
PROD (über zdb_prod-Link) | TEST |
clone-prod-to-testmig |
PROD | TESTMIG |
Was passiert:
Ziel-PDB wird gedroppt (alle Daten weg).
Neue PDB als Kopie der Quelle.
APEX-Banner gesetzt (z.B. "ZODT01 TEST @ZGONC PROD-COPY @ 19.06.2026 14:30").
ZDB-DB-Link auf TSTB neu erstellt.
ADM-Params gesetzt (
app_env=TEST,zdb_global_name=TSTB.ZGONC.AT,log_level=DEBUGusw.).APEX
set_analytics_envundset_theme_envaufgerufen.APEX Activity-Log truncated.
PDB unrestricted öffnen, Save State.
⚠ Vor dem Start: Die Pipeline blockt für eine explizite Bestätigung ("Alle Daten auf TESTMIG gehen verloren"). Trotzdem: prüfe immer, dass du die richtige Quelle/Ziel-Kombi gewählt hast.
Migrate
Gruppe: Migrate
Drei Single-Step-Pipelines und zwei Full-Run-Pipelines:
migrate-step-pre— Pre-Migration nur (Trigger off, APEX-Apps off,p_mig_v050.pre_mig)migrate-step-run— Run-Migration nur (NLS auf Deutsch,p_mig_v050.execute_migration). Kann mehrere Stunden dauern.migrate-step-post— Post-Migration nurmigrate-full-testmig— alle drei in Folge auf TESTMIGmigrate-full-test— alle drei in Folge auf TEST
Die Step-Pipelines erwarten einen connection-Input — du tippst dort manuell die Connection-Name (z.B. zodtmig-erp-base). Die Full- Pipelines haben die Connection hardcoded.
8. Connections und Passwörter pflegen
Admin → Bundled Connections
Hier verwaltest du DB-Connections, die das Tool für Pipeline-Stages verwendet. Jede Connection hat einen Namen (referenziert von Pipelines über connection: <name>) und Verbindungsdaten (user, password, host, port, service_name).
Workflow:
Klick + Neue Connection oder Aus SQLcl-Wallet importieren (zeigt alle Wallet-Einträge, du wählst aus, Passwort tippst du selbst — wird nicht aus dem Wallet gelesen).
Felder ausfüllen, Test klickt einen Connection-Test bevor du speicherst.
Speichern → in
data/connections.jsonverschlüsselt abgelegt.
Admin → Connections prüfen
Klick → Tool checkt:
Welche YAML- + Bundled-Connections existieren im SQLcl-Wallet?
Welche Connections werden in Pipelines referenziert aber sind weder bundled noch YAML?
Damit fällt früh auf, wenn du eine neue Pipeline geschrieben hast die gegen eine fehlende Connection läuft.
Admin → Pipeline Secrets
Hier hinterlegst du Werte wie Password, OtherPassword. Diese werden bei jedem Pipeline-Run automatisch als ${Password} etc. in allen YAMLs verfügbar gemacht. Eingaben in der Pipeline-Form (falls die Pipeline ein gleichnamiges Input definiert) überschreiben das Secret.
Verschlüsselt in data/secrets.json. UI zeigt nur Längen, nie die Werte selbst.
9. Pipelines und Features bearbeiten
Navbar → 📝 Pipelines (oder 📦 Features)
Linke Sidebar listet alle YAMLs. Klick → YAML wird im Editor angezeigt. Du kannst direkt editieren.
Validate — parst die YAML ohne zu speichern, zeigt Fehler.
Speichern — schreibt die Datei, hot-reload (laufende Runs sehen den alten Stand, neue Runs den neuen). Automatisch wird ein
.bak-Backup angelegt und der Commit landet im maintenance-Repo (falls Auto-Commit aktiv).
Bei Features wird zusätzlich angezeigt welche Pipelines das Feature includen ("verwendet von: candidat, test, prod"). Beim Speichern werden diese Pipelines automatisch re-expandiert.
Wenn du eine neue Pipeline oder ein neues Feature anlegen willst: + Neu klicken, ID eingeben (a-z, 0-9, -, _), Skeleton wird generiert.
10. Workdir-Management
Admin → 📁 Workdir / ERP-Repo
Status:
Aktueller Workdir-Pfad (kommt aus
settings.yamloderworkdir.json)Branch
Working tree: clean / dirty
Ahead / Behind vs origin
Remote-URL
Letzter Commit
Aktionen:
🔄 Refresh — neu abfragen
git fetch — Remote-Stand aktualisieren ohne zu mergen
git pull — fetch + merge
Pfad speichern — anderen lokalen Pfad als Workdir setzen
Repository klonen — wenn der Pfad leer ist: klonen direkt aus der UI
Wenn Working tree dirty: zusätzliche Box "Uncommittete Änderungen" mit Liste der modifizierten/neuen/gelöschten Files, Commit-Message-Input und 💾 Commit / ⬆ Push only-Buttons. Damit kannst du Änderungen aus dem Tool direkt committen+pushen ohne ins Terminal zu gehen.
Branch-Indikator in der Navbar (🌿) — zeigt jederzeit den aktuellen Branch und ob das Working tree dirty ist (
*-Suffix), wie viele Commits ahead oder behind. Auto-Refresh alle 60s.
11. Tool-Updates einspielen
Admin → ⬆️ Tool-Update einspielen
🔎 Check — fetcht das maintenance-Repo und zeigt wieviele neue Commits anliegen, mit Hashes und Commit-Messages.
Update starten — startet das Update:
git pull --rebaseim maintenance-Reponpm install --include=devnpm run buildnpm prune --omit=devServer schickt sich SIGTERM, systemd startet neu
Live-Log unten zeigt den Fortschritt. Wenn der Server neu gestartet ist, erkennt die UI das automatisch (PID-Wechsel) und meldet "✓ Update durch".
- Reset — wenn der "läuft bereits"-Flag aus irgendeinem Grund hängengeblieben ist (z.B. nach einem Build-Fehler), kannst du ihn manuell löschen.
Achtung: laufende Pipelines werden durch den Restart abgebrochen. Der Confirm-Dialog warnt davor.
12. Hilfreiche Details
Version-Default
Wenn dein Workdir-Branch release-candidat_0.6.2 heißt, wird 0.6.2 als Default in das Versions-Feld eingetragen. Sonst nimmt das Tool die Version des letzten Runs, falls vorhanden. Sonst die suggestedVersion aus <workdir>/.dbtools/project.config.json (= letzte Release-Version + 1).
Last Deploy Date abfragen
In Pipeline-Forms mit Last Deploy Date-Feld gibt's einen kleinen Button daneben. Klick fragt das aktuelle Deploy-Date aus adm_version via Connection ab und füllt das Feld.
Log-Layout
Splitter zwischen Stage-Liste und Log ist ziehbar — Doppelklick = Reset auf 45/55. Log komplett wegklappen mit dem ✕ im Log-Header (oben rechts). "Log ›"-Button kommt zurück.
Logs sind auch als Plain-Text-Datei verfügbar — Download-Button im Run-Header (⤓ Log) lädt zodis-run-<id>.log.
Cancel killt SQLcl-Worker
Wenn du auf Abbrechen klickst während ein parallel-sqlcl-Run läuft, werden alle SQLcl-Worker sofort gekillt (SIGTERM, nach 2s SIGKILL). Du musst nicht warten bis sie von selbst beenden.
SQLcl JVM Heap
Admin → ⚙️ SQLcl JVM Memory
Wenn ein SQLcl-Job mit Exit-Code 137 stirbt, ist das der Linux OOM-Killer. Bei mehreren parallelen Workern auf einer kleinen VM kann das passieren. Du kannst hier Heap-Max (Default 512 MB) anpassen — Änderung greift bei jedem nächsten SQLcl-Spawn, kein Tool-Restart nötig.
Faustregel: workers × heapMax + 1 GB Sicherheit < verfügbares RAM.
SQLcl Version
Admin → 🔌 SQLcl Version & Installation
Zeigt:
Welche Version ist installiert (
vendor/sqlcl/)Welche Version wünschst du dir (settings.yaml)
Welche Version verlangt das aktuelle SQLcl-Project (
<workdir>/.dbtools/project.config.json)
Wenn was nicht passt, kannst du auf Installieren klicken. Default lädt die aktuellste GA-Version von Oracle. Optional kannst du eine spezifische Version oder eine URL angeben (für Air-Gapped Setups oder Beta-Builds).
Project-Config editieren
Admin → 📐 SQLcl-Project Config (.dbtools/)
Editor für die Files unter <workdir>/.dbtools/ (project.config.json, project.sqlformat.xml, filters/project.filters etc.).
Edits sind nur erlaubt wenn der Workdir auf main steht — damit Config-Änderungen nicht versehentlich im Release-Candidat-Branch landen. Auf release-candidat_*-Branches ist das Feld read-only.
Backups (.admin-bak) werden einmalig pro Datei angelegt.
Run abbrechen statt warten
Wenn du einen Run gestartet hast und merkst, dass etwas falsch konfiguriert war: Abbrechen im Run-Header. Status geht auf cancelled, alle Children gekillt. Neuer Run anlegen, fertig.
Die alten Run-Daten bleiben in der Sidebar für Audit/Vergleich.
Zusammenfassung typischer Aufgaben
| Aufgabe | Pipeline | Notiz |
|---|---|---|
| Neuer Release-Kandidat aus DEV | Release-Kandidat erstellen |
Beginnt mit Code-Freeze |
| Candidat-Verifikation | Testmig Re-Run |
Zwei Approval-Gates |
| Candidat wegwerfen | Candidat verwerfen |
Reset hard auf main |
| Release finalisieren | Release finalisieren |
Merge in main, Tag, Push |
| Deploy auf TEST | Deployment auf TEST |
Voller Post-Deploy-Flow |
| Deploy auf PROD | Deployment auf PROD |
Mit Downtime + Apps off |
| Nur APEX auf TEST | APEX-Only Deploy auf TEST |
Ohne Schema-Changes |
| TEST aus PROD-Kopie | clone-prod-to-test |
TEST geht komplett weg |
| Migration laufen lassen | migrate-full-testmig |
Kann Stunden dauern |
| Tool aktualisieren | Admin → ⬆️ Tool-Update einspielen | Restart nötig |
Bei Fragen: das Stage-Approval-Gate ist dein Freund. Im Zweifel ✗ Run abbrechen und mit dem Team Rücksprache halten. Pipelines sind idempotent für done-Stages — beim Neustart eines failed Runs werden schon-fertige Stages übersprungen.