chore: migrate to Exposed 1.0.0 and refactor UUID handling
Updated persistence layer to align with Exposed 1.0.0. Refactored table definitions to use `javaUUID` for consistency with `java.util.UUID`. Adjusted transaction handling for compatibility with the latest API changes. Enhanced error handling in database utility functions and refined pagination logic. Added documentation and migration updates for best practices with Exposed 1.0.0.
This commit is contained in:
+23
-3
@@ -96,19 +96,39 @@ Das Handling von JSONB-Spalten in SQLite wurde vereinheitlicht.
|
||||
5. JSON/SQLite:
|
||||
- Verhalten von `jsonb()` mit `castToJsonFormat` prüfen und ggf. deaktivieren.
|
||||
|
||||
## 3. Test-Matrix
|
||||
## 3. Troubleshooting & Lessons Learned (Update 2026-02-02)
|
||||
|
||||
### 3.1 Low-Level JDBC Zugriff (`exec`, `executeUpdate`)
|
||||
|
||||
Bei der Migration von `DatabaseUtils.kt` traten Probleme mit der Auflösung von `exec` und `executeUpdate` auf.
|
||||
|
||||
* **Problem:** Die generische `Transaction` Klasse bietet in Exposed 1.0.0 keinen direkten Zugriff mehr auf `exec` mit `ResultSet`-Verarbeitung oder `executeUpdate`. Diese Methoden sind nun spezifischer in `JdbcTransaction` oder `PreparedStatementApi` verortet.
|
||||
* **Lösung:**
|
||||
* **Explizite `JdbcTransaction`:** Unsere Transaction-Wrapper (`transactionResult`) wurden angepasst, um `JdbcTransaction` als Receiver (`this`) zu erzwingen.
|
||||
* **`exec` mit `StatementType`:** Aufrufe von `exec` müssen nun den `explicitStatementType` Parameter (z.B. `StatementType.SELECT`) nutzen, damit der Compiler die korrekte Überladung wählt.
|
||||
* **`executeUpdate` Workaround:** Da `PreparedStatementApi` in Exposed 1.0.0 nicht `AutoCloseable` ist und `executeUpdate` teilweise schwer aufzulösen war, nutzen wir `try-finally` mit `closeIfPossible()` und greifen bei Bedarf auf die native JDBC Connection zu.
|
||||
|
||||
```kotlin
|
||||
// Beispiel für korrekten Low-Level Zugriff in Exposed 1.0.0
|
||||
transactionResult(database) {
|
||||
// 'this' ist JdbcTransaction
|
||||
this.exec("SELECT ...", explicitStatementType = StatementType.SELECT) { rs -> ... }
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Test-Matrix
|
||||
|
||||
- Unit: DSL-Typen (UUID, Zeittypen), Mappings, einfache Inserts/Selects.
|
||||
- Integration: JDBC/Hikari Konfiguration, `batchInsert`, Upsert/Ignore-Pfade.
|
||||
- E2E (Docker): CRUD-Flows über den Service hinweg; Metriken/Health.
|
||||
|
||||
## 4. Rollback-Plan
|
||||
## 5. Rollback-Plan
|
||||
|
||||
- `git revert` des Version-Bumps in `libs.versions.toml` und ggf. betroffener Anpassungs-Commits.
|
||||
- Rebuild; E2E-Smoketest durchführen.
|
||||
- Dokumentenstatus auf `ARCHIVED` setzen oder Nachtrag mit „Rollback erfolgt“ ergänzen.
|
||||
|
||||
## 5. Diagramm (Flow)
|
||||
## 6. Diagramm (Flow)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
type: Guide
|
||||
status: DRAFT
|
||||
owner: Backend Developer
|
||||
date: 2026-02-02
|
||||
---
|
||||
|
||||
# Database Best Practices & Exposed 1.0.0
|
||||
|
||||
Dieser Guide beschreibt den korrekten Umgang mit der Datenbank-Schicht in unseren Backend-Services, basierend auf JetBrains Exposed 1.0.0.
|
||||
|
||||
## 1. Architektur-Prinzipien
|
||||
|
||||
* **Trennung:** Datenbank-Zugriffe gehören ausschließlich in die `infrastructure/persistence` Schicht. Services nutzen Repositories (Interfaces), keine direkten Exposed-Aufrufe.
|
||||
* **Transaktionen:** Jede geschäftliche Operation sollte in einer Transaktion laufen. Nutze dafür die Helper aus `DatabaseUtils.kt`.
|
||||
|
||||
## 2. Nutzung von `DatabaseUtils`
|
||||
|
||||
Wir haben zentrale Wrapper für Transaktionen, um Fehlerbehandlung und Logging zu vereinheitlichen.
|
||||
|
||||
### 2.1 Transaktionen starten
|
||||
|
||||
Nutze immer `transactionResult` (oder die Aliase `readTransaction` / `writeTransaction`), um Exposed-Code auszuführen.
|
||||
|
||||
```kotlin
|
||||
fun findUser(id: UUID): Result<User> = readTransaction {
|
||||
// 'this' ist hier eine JdbcTransaction
|
||||
UserTable.select { UserTable.id eq id }
|
||||
.map { ... }
|
||||
.singleOrNull()
|
||||
}
|
||||
```
|
||||
|
||||
**Wichtig:** Der Lambda-Receiver ist `JdbcTransaction`. Das ermöglicht Zugriff auf Low-Level JDBC Funktionen, falls nötig.
|
||||
|
||||
### 2.2 Low-Level SQL (`exec`, `executeUpdate`)
|
||||
|
||||
Vermeide rohes SQL, wo immer möglich. Wenn es sein muss (z.B. für Performance-Optimierungen oder spezielle Postgres-Features), beachte folgende Regeln für Exposed 1.0.0:
|
||||
|
||||
* **`exec`:** Nutze immer `explicitStatementType`.
|
||||
```kotlin
|
||||
this.exec("SELECT 1", explicitStatementType = StatementType.SELECT) { rs -> ... }
|
||||
```
|
||||
* **`executeUpdate`:** Nutze die Helper-Methode `DatabaseUtils.executeUpdate`, da sie sich um das korrekte Schließen von Statements kümmert (Exposed `PreparedStatementApi` ist nicht `AutoCloseable`).
|
||||
|
||||
## 3. Exposed 1.0.0 Besonderheiten
|
||||
|
||||
* **UUIDs:** Nutze `Table.javaUUID()` für `java.util.UUID` Spalten. `Table.uuid()` ist für `kotlin.uuid.Uuid` reserviert.
|
||||
* **JSONB:** Bei SQLite wird JSON automatisch gewrappt. Prüfe `castToJsonFormat` Flag.
|
||||
|
||||
## 4. Fehlerbehandlung
|
||||
|
||||
`DatabaseUtils` fängt `SQLException` ab und mappt sie auf unsere Domain-Fehler (`ErrorDto`):
|
||||
* Duplicate Key -> `ErrorCodes.DUPLICATE_ENTRY`
|
||||
* Foreign Key -> `ErrorCodes.FOREIGN_KEY_VIOLATION`
|
||||
* Timeout -> `ErrorCodes.DATABASE_TIMEOUT`
|
||||
|
||||
Wirf keine rohen Exceptions aus Repositories.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
type: Journal
|
||||
status: COMPLETED
|
||||
owner: Lead Architect
|
||||
date: 2026-01-29
|
||||
participants:
|
||||
- Lead Architect
|
||||
---
|
||||
|
||||
# Session Log: 29. Jänner 2026 - Roadmap Update & Phase 4 Kickoff
|
||||
|
||||
## Zielsetzung
|
||||
Aktualisierung der MASTER ROADMAP nach erfolgreichem Abschluss der "Tracer Bullet" Phase und Vorbereitung auf den Start der fachlichen Implementierung (Phase 4).
|
||||
|
||||
## Durchgeführte Arbeiten
|
||||
|
||||
### 1. Status-Review
|
||||
* Der "Tracer Bullet" (Ping-Service) ist erfolgreich durch den gesamten Stack implementiert.
|
||||
* Kritische technische Hürden (SQLDelight Async, Docker Networking, ArchUnit) sind genommen.
|
||||
* Das Projekt ist bereit für die Skalierung auf echte Fach-Domänen.
|
||||
|
||||
### 2. Roadmap Update
|
||||
* **Phase 1-3:** Als "ABGESCHLOSSEN" markiert.
|
||||
* **Phase 4 (Production Packaging & Domain Start):** Als "AKTUELL" definiert.
|
||||
* **Neue Aufgaben:**
|
||||
* **DevOps:** Dockerisierung des Frontends.
|
||||
* **Backend:** Erstellung des `event-service`.
|
||||
* **Frontend:** Erstellung des `events`-Features.
|
||||
* **Architecture:** Sicherstellung der ArchUnit-Abdeckung für neue Module.
|
||||
|
||||
### 3. Architecture Review Vorbereitung
|
||||
* Die bestehenden ArchUnit-Tests (`BackendArchitectureTest`, `FrontendArchitectureTest`) wurden analysiert.
|
||||
* **Erkenntnis:**
|
||||
* Backend-Tests erfordern manuelle Erweiterung der Package-Liste (`at.mocode.events..`).
|
||||
* Frontend-Tests erfordern strikte Einhaltung der Package-Struktur (`at.mocode.<domain>.feature`).
|
||||
* Diese Anforderungen wurden explizit in die Roadmap-Tasks aufgenommen.
|
||||
|
||||
## Ergebnis & Status
|
||||
* Die Roadmap ist aktuell und spiegelt den Projektfortschritt wider.
|
||||
* Die Aufgaben für die spezialisierten Agenten sind klar definiert.
|
||||
* Der Fokus liegt nun auf der Erstellung der ersten echten Fachlichkeit ("Events").
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
type: Journal
|
||||
status: COMPLETED
|
||||
owner: Lead Architect
|
||||
date: 2026-01-30
|
||||
participants:
|
||||
- Lead Architect
|
||||
---
|
||||
|
||||
# Session Log: 30. Jänner 2026 - Refactoring Exposed & Ktor
|
||||
|
||||
## Zielsetzung
|
||||
Durchführung der strategischen Migration auf Exposed 1.0.0 (Stable) und Ktor 3.4.0, basierend auf den technischen Analyseberichten.
|
||||
|
||||
## Durchgeführte Arbeiten
|
||||
|
||||
### 1. Versions-Update (`libs.versions.toml`)
|
||||
* **Exposed:** Aktualisiert von `1.0.0-rc-4` auf `1.0.0`.
|
||||
* **Ktor:** Aktualisiert von `3.3.3` auf `3.4.0`.
|
||||
* **Neue Dependency:** `ktor-server-routing-openapi` hinzugefügt (für Backend OpenAPI Fix).
|
||||
|
||||
### 2. Exposed Migration (Backend)
|
||||
* **Problem:** `DatabaseUtils.kt` enthielt veraltete/falsche Imports (`org.jetbrains.exposed.v1...`), die nicht mit Exposed 1.0.0 kompatibel sind.
|
||||
* **Lösung:** Die Imports wurden auf die Standard-Exposed-Packages (`org.jetbrains.exposed.sql...`) korrigiert.
|
||||
* **UUID-Thematik:** Die Tabellen-Definitionen (`VeranstaltungTable`, etc.) nutzen weiterhin `UUIDTable`. Es besteht das Risiko, dass Exposed 1.0.0 hier auf `kotlin.uuid.Uuid` gewechselt hat. Dies muss beim nächsten Build verifiziert werden. Falls Kompilierfehler auftreten, müssen die Tabellen auf `javaUUID` bzw. `JavaUUIDTable` (falls existent) migriert werden.
|
||||
|
||||
### 3. Ktor Migration (Frontend & Backend)
|
||||
* **Frontend:** Das Build-Skript `frontend/core/network/build.gradle.kts` nutzt separate `js` und `wasmJs` Blöcke, daher war keine Umbenennung von `jsAndWasmShared` notwendig.
|
||||
* **Backend:** Die Dependency `ktor-server-routing-openapi` wurde im Katalog bereitgestellt. Da die Backend-Module (Events, Horses, Masterdata) Ktor Server nutzen, aber keine explizite OpenAPI-Nutzung im Code gefunden wurde (wahrscheinlich SpringDoc), wurde hier kein Code geändert.
|
||||
|
||||
## Offene Punkte / Risiken
|
||||
* **UUID Kompatibilität:** Die Verwendung von `UUIDTable` im Backend muss gegen Exposed 1.0.0 getestet werden. Es ist möglich, dass hier Breaking Changes zur Laufzeit oder Compile-Zeit auftreten.
|
||||
* **Ktor JS Target:** Die separate Konfiguration von `js` und `wasmJs` ist funktional, aber das neue `web` Target wäre zukunftssicherer.
|
||||
|
||||
## Nächste Schritte
|
||||
1. **Build & Test:** Ausführen des kompletten Builds (`./gradlew build`), um Kompilierfehler (insb. UUIDs) zu identifizieren.
|
||||
2. **Runtime Test:** Starten des Backends und Prüfung der Datenbank-Interaktion.
|
||||
Reference in New Issue
Block a user