chore: initial commit

Author: chrootlogin

.gitignore

@@ -0,0 +1,7 @@
+_build
+slide-output
+node_modules
+slides/_build
+docs/_build
+.venv
+uv.lock

LICENSE

@@ -0,0 +1,80 @@
+# Database Development
+
+Dieses Repository enthält die Materialien für **Database Development**, das Folgemodul zu **Relational Databases** an der HFTM.
+
+## Ziel des Kurses
+
+Der Kurs zeigt, wie relationale Datenbanken in professioneller Softwareentwicklung eingesetzt werden. Im Zentrum steht die Frage:
+
+> Wie entwickle ich mit PostgreSQL, Spring Boot, Hibernate/JPA und Flyway eine robuste, wartbare und performante datenbankgestützte Anwendung?
+
+Die konkrete Unterrichtstechnologie ist Spring Boot. Die behandelten Prinzipien bleiben aber bewusst übertragbar: Datenmodellierung, ORM, Migrationen, Transaktionen, Query Design, Performance und Tests.
+
+## Leitfallstudie
+
+Alle Materialien arbeiten mit einem **Ticket-System für internen Support**. Die Fallstudie ist klein genug für Unterrichtslektionen und reich genug für typische Datenbankentwicklungsfragen:
+
+- Benutzer, Teams und Zuständigkeiten
+- Tickets mit Status, Priorität und Verantwortlichen
+- Kommentare und Ereignisverlauf
+- Labels und n:m-Beziehungen
+- Reporting-Abfragen, Transaktionen, Migrationen und Performance-Fragen
+
+## Struktur
+
+- `docs/` - Lehrbuch im MyST/Jupyter-Book-Format
+- `slides/` - Marp-Folien mit HFTM-Theme
+- `planning/` - Unterrichtsplanung
+- `exercises/` - Diagnose- und Übungsaufgaben
+- `postgres/` - PostgreSQL-Container, Schema und Testdaten
+
+## Voraussetzungen
+
+- Python 3.12+
+- Poetry
+- Node.js 18+
+- Docker oder Podman
+
+## Lehrbuch bauen
+
+```bash
+poetry install
+cd docs
+jupyter book build --site
+```
+
+Mit aktivierter Poetry-Umgebung kannst du alternativ aus dem Projektroot bauen:
+
+```bash
+npm run docs:build
+```
+
+Hinweis: `jupyter book build .` funktioniert mit dem MyST-basierten Jupyter-Book-CLI nicht, weil `.` als Dateiargument interpretiert wird.
+
+## Folien starten
+
+```bash
+npm install
+npm run slides:serve
+```
+
+Die Folien werden standardmässig auf Port `5002` bereitgestellt.
+
+## PostgreSQL-Fallstudie starten
+
+```bash
+cd postgres
+docker compose up --build
+```
+
+Verbindungsdaten:
+
+- Host: `localhost`
+- Port: `5433`
+- Datenbank: `ticket_system`
+- Benutzer: `ticket_user`
+- Passwort: `ticket_user`
+
+## Lizenz
+
+Dieses Werk steht unter der Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA 4.0).

README.md

@@ -0,0 +1,11 @@
+# Zitierleitfaden
+
+Quellen werden im Lehrbuch mit MyST-Zitationen direkt im Text referenziert:
+
+```markdown
+{cite}`citation_key`
+```
+
+Die zugehörigen BibTeX-Einträge liegen in `docs/references.bib`.
+
+Für selbst erstellte Aufgaben, grundlegende SQL-Syntax und eigene Unterrichtsbeispiele ist keine Zitation nötig. Extern belegte technische Aussagen, historische Einordnungen oder konkrete Aussagen zu Frameworks erhalten eine Quelle.

citation_guide.md

@@ -0,0 +1,65 @@
+# Database Development
+
+Willkommen zu **Database Development**, dem Folgemodul zu **Relational Databases**.
+
+In **Relational Databases** hast du relationale Datenbanken aus Sicht von SQL, Modellierung, Normalisierung, Transaktionen und ersten ORM-Konzepten kennengelernt. In **Database Development** verschiebt sich die Perspektive: Die Datenbank ist nicht mehr nur ein System, das du bedienst. Sie wird Teil einer Softwarearchitektur.
+
+Die zentrale Frage lautet:
+
+> Wie entwickelst du mit PostgreSQL, Spring Boot, Hibernate/JPA und Flyway eine robuste, wartbare und performante datenbankgestützte Anwendung?
+
+Spring Boot ist in diesem Kurs die konkrete Lernumgebung {cite}`spring_boot_reference`. Für den Datenbankzugriff arbeiten wir mit Spring Data JPA und Hibernate/JPA {cite}`spring_data_jpa_reference` {cite}`hibernate_orm_user_guide`. Schemaänderungen werden mit Flyway als versionierte Migrationen gedacht {cite}`flyway_documentation`. PostgreSQL bleibt unser relationales Referenzsystem {cite}`postgresql_documentation`.
+
+:::{important} Lernziele des Moduls
+Nach Abschluss des Moduls kannst du:
+
+- ein kleines Spring-Boot-Backend mit PostgreSQL fachlich sinnvoll strukturieren.
+- Datenmodelle mit JPA Entities, Beziehungen, Constraints und DTO-Abgrenzung abbilden.
+- Flyway-Migrationen planen, schreiben und Risiken von Schemaänderungen einschätzen.
+- Transaktionsgrenzen im Anwendungscode mit `@Transactional` begründen.
+- Repository Methods, JPQL und native SQL Queries situationsgerecht einsetzen.
+- typische ORM-Probleme wie N+1, falsches Lazy Loading und ungeeignete Abfragen erkennen.
+- Query-Performance mit `EXPLAIN`, einfachen Indexüberlegungen und API-Zugriffsmustern beurteilen.
+- Integrationstests gegen echte PostgreSQL-Instanzen konzeptionell einordnen, etwa mit Testcontainers {cite}`testcontainers_documentation`.
+:::
+
+## Die Leitfallstudie
+
+Wir arbeiten durchgehend mit einem **Ticket-System für internen Support**. Dieses System ist absichtlich nah an typischen Entwicklungsprojekten:
+
+- Mitarbeitende erstellen Tickets.
+- Support-Teams übernehmen Zuständigkeiten.
+- Tickets haben Status, Priorität, Kommentare und Ereignisse.
+- Labels erlauben flexible Kategorisierung.
+- Reporting-Abfragen zeigen Trends und Engpässe.
+
+Diese Fallstudie ist klein genug, damit du sie im Unterricht überblicken kannst. Gleichzeitig enthält sie genug Reibung für echte Datenbankentwicklungsfragen: Transaktionsgrenzen, n:m-Beziehungen, Migrationen, ORM-Ladestrategien, Reporting Queries und Performance.
+
+## Aufbau des Moduls
+
+Das Modul umfasst neun Blöcke zu je drei Lektionen:
+
+| Block | Thema | Schwerpunkt |
+| --- | --- | --- |
+| 1 | Wiederholung und Standortbestimmung | Relevantes Vorwissen aus **Relational Databases** aktivieren |
+| 2 | Spring Boot, PostgreSQL und Datenbankzugriff | Projektstruktur, Konfiguration, Repository- und Service-Layer |
+| 3 | Hibernate/JPA Grundlagen | Entities, Beziehungen, Repositories, CRUD |
+| 4 | Transaktionen und Datenkonsistenz | `@Transactional`, Rollback, Invarianten |
+| 5 | Schema Design für Softwareprojekte | Constraints, IDs, Statusmodellierung, DTO-Abgrenzung |
+| 6 | Flyway und Schema Evolution | Migrationen, Datenmigrationen, sichere Änderungsschritte |
+| 7 | Query Design | Repository Methods, JPQL, native SQL und Reporting |
+| 8 | Performance und ORM-Probleme | N+1, Lazy/Eager Loading, Pagination, `EXPLAIN`, Indexe |
+| 9 | Projektarbeit und Prüfungsvorbereitung | Review, Konsolidierung, Prüfungstraining |
+
+## Arbeitsweise
+
+Du wirst in diesem Modul viel lesen, vergleichen und begründen. Das ist Absicht. Datenbankentwicklung besteht nicht nur darin, Code zum Laufen zu bringen. Gute Entwicklerinnen und Entwickler können erklären, warum eine Beziehung so modelliert ist, warum eine Query so geschrieben wurde, wo eine Transaktion beginnt und weshalb eine Migration sicher oder riskant ist.
+
+Die Blöcke folgen deshalb einem wiederkehrenden Muster:
+
+1. Ein realistisches Problem aus der Softwareentwicklung.
+2. Eine kompakte fachliche Einordnung.
+3. Eine angeleitete Umsetzung oder Analyse.
+4. Eine Transferfrage für ähnliche Situationen.
+
+Im ersten Block beginnen wir mit einer Standortbestimmung. Sie zeigt, welche Grundlagen aus **Relational Databases** du bereits sicher einsetzen kannst und welche Themen in **Database Development** bewusst vertieft werden.

docs/0_intro.md

@@ -0,0 +1,21 @@
+# Wiederholung und Standortbestimmung
+
+Der erste Block verbindet **Relational Databases** mit **Database Development**. Du wiederholst nicht die ganze Welt relationaler Datenbanken. Stattdessen aktivierst du genau jene Grundlagen, die in einer datenbankgestützten Anwendung sofort wichtig werden:
+
+- SQL-Abfragen lesen und korrigieren
+- Beziehungen und Constraints verstehen
+- Transaktionen fachlich begründen
+- ORM und direktes SQL einordnen
+- Schemaänderungen als Teil von Softwareentwicklung sehen
+
+Die Leitfallstudie ist ein internes Ticket-System. Es ist bewusst einfach genug für eine Standortbestimmung, aber realistisch genug für spätere Blöcke zu Spring Boot, JPA, Flyway und Performance.
+
+:::{important} Lernziele
+Nach diesem Block kannst du:
+
+- das Ticket-Schema fachlich erklären.
+- typische SQL-Abfragen mit Joins und Aggregationen nachvollziehen.
+- wichtige Constraints und Beziehungstypen begründen.
+- eine einfache Transaktionsgrenze für einen kritischen Vorgang skizzieren.
+- erklären, weshalb Wissen aus **Relational Databases** in Anwendungscode sichtbar bleibt.
+:::

docs/1_review_orientation/0_intro.md

@@ -0,0 +1,40 @@
+# Was aus Relational Databases jetzt zählt
+
+In **Relational Databases** hast du viele Grundlagen kennengelernt. Für **Database Development** sind nicht alle gleich wichtig. Entscheidend ist, ob du sie in einer Anwendungssituation wiedererkennst.
+
+Stell dir vor, ein API-Endpunkt soll alle offenen Tickets eines Teams anzeigen. Schon diese scheinbar einfache Anforderung berührt mehrere Themen aus **Relational Databases**:
+
+- Welche Tabellen sind beteiligt?
+- Welche Beziehung ist verpflichtend, welche optional?
+- Braucht es `JOIN` oder `LEFT JOIN`?
+- Welche Spalten werden gefiltert?
+- Welche Constraints schützen die Daten, falls der Anwendungscode fehlerhaft ist?
+- Kann das ORM die Abfrage sinnvoll erzeugen oder braucht es gezieltes SQL?
+
+## SQL als gemeinsame Sprache
+
+Auch wenn spätere Blöcke mit Spring Data JPA und Hibernate arbeiten, bleibt SQL die gemeinsame Sprache zwischen Anwendung und Datenbank. Ein Repository kann dir Schreibarbeit abnehmen. Es nimmt dir aber nicht die Verantwortung ab, Datenzugriffe zu verstehen.
+
+Besonders wichtig bleiben:
+
+- `SELECT`, `WHERE`, `ORDER BY`
+- `JOIN`, `LEFT JOIN`
+- `GROUP BY`, Aggregatfunktionen und `HAVING`
+- Primärschlüssel, Fremdschlüssel und eindeutige Werte
+- Transaktionen mit Commit und Rollback
+
+## Modellierung als Architekturentscheidung
+
+Eine Datenbankstruktur ist nicht nur eine technische Ablageform. Sie prägt, wie Anwendungscode aussieht. Eine falsch modellierte n:m-Beziehung führt später zu umständlichen Queries, komplizierten DTOs oder fehleranfälliger Geschäftslogik.
+
+Im Ticket-System ist die Beziehung zwischen Tickets und Labels ein gutes Beispiel. Ein Ticket kann mehrere Labels haben, und ein Label kann zu vielen Tickets gehören. Deshalb braucht es eine Zwischentabelle `ticket_labels`. Ein Textfeld mit kommagetrennten Labels wäre schneller hingeschrieben, aber schlechter abfragbar, schwerer validierbar und weniger robust.
+
+## Transaktionen als Schutz fachlicher Abläufe
+
+Transaktionen werden in **Database Development** aus Anwendungssicht betrachtet. Du fragst nicht nur: "Was ist ACID?", sondern:
+
+> Welche Schritte müssen gemeinsam erfolgreich sein, damit der fachliche Zustand korrekt bleibt?
+
+Beim Erstellen eines Tickets gehören beispielsweise Ticket, erster Kommentar und Ereigniseintrag zusammen. Wenn der Kommentar fehlschlägt, soll nicht trotzdem ein halbfertiges Ticket übrig bleiben.
+
+Genau hier wird später `@Transactional` im Service-Layer wichtig.

docs/1_review_orientation/1_relational_databases_reactivation.md

@@ -0,0 +1,61 @@
+# Die Ticket-Fallstudie
+
+Das Ticket-System bildet interne Supportprozesse ab. Es enthält Mitarbeitende, Support-Teams, Tickets, Kommentare, Ereignisse und Labels.
+
+```mermaid
+erDiagram
+    TEAMS ||--o{ USERS : has
+    TEAMS ||--o{ TICKETS : owns
+    USERS ||--o{ TICKETS : creates
+    USERS ||--o{ TICKETS : handles
+    TICKETS ||--o{ TICKET_COMMENTS : contains
+    USERS ||--o{ TICKET_COMMENTS : writes
+    TICKETS ||--o{ TICKET_EVENTS : records
+    USERS ||--o{ TICKET_EVENTS : triggers
+    TICKETS ||--o{ TICKET_LABELS : has
+    LABELS ||--o{ TICKET_LABELS : classifies
+```
+
+## Zentrale Tabellen
+
+| Tabelle | Zweck |
+| --- | --- |
+| `users` | Personen, die Tickets erstellen oder bearbeiten |
+| `teams` | Zuständigkeiten und organisatorische Gruppen |
+| `tickets` | eigentliche Support-Fälle |
+| `ticket_comments` | Kommunikation und interne Notizen |
+| `ticket_events` | nachvollziehbarer Verlauf wichtiger Änderungen |
+| `labels` | wiederverwendbare Kategorien |
+| `ticket_labels` | n:m-Zuordnung zwischen Tickets und Labels |
+
+## Warum diese Fallstudie passt
+
+Das Ticket-System ist für Softwareentwickler intuitiv. Gleichzeitig entstehen echte Datenbankfragen:
+
+- Ein Ticket muss genau ein erstellendes Benutzerkonto haben.
+- Ein Ticket kann noch keiner verantwortlichen Person zugewiesen sein.
+- Ein Ticket kann mehrere Labels erhalten.
+- Status und Priorität sollen kontrollierte Werte haben.
+- Kommentar und Event müssen oft in derselben Transaktion gespeichert werden.
+- Reporting braucht Joins und Aggregationen.
+
+## Beispielabfrage
+
+Die folgende Query zeigt offene Tickets mit Team und verantwortlicher Person. Weil ein Ticket noch nicht zugewiesen sein muss, wird für die verantwortliche Person ein `LEFT JOIN` verwendet.
+
+```sql
+SELECT
+    t.id,
+    t.title,
+    t.status,
+    t.priority,
+    team.name AS team_name,
+    assignee.display_name AS assigned_to
+FROM tickets t
+JOIN teams team ON team.id = t.team_id
+LEFT JOIN users assignee ON assignee.id = t.assigned_to_id
+WHERE t.status NOT IN ('resolved', 'closed')
+ORDER BY t.priority DESC, t.created_at;
+```
+
+Diese Query ist klein, aber sie zeigt bereits die Richtung des Kurses: Datenbankmodell, fachliche Bedeutung und späterer API-Zugriff gehören zusammen.

docs/1_review_orientation/2_ticket_case_study.md

@@ -0,0 +1,46 @@
+# Diagnoseaufgabe
+
+Die Standortbestimmung ist eine Lernaufgabe, keine Falle. Sie zeigt, welche Grundlagen du sicher abrufen kannst und wo du in den nächsten Blöcken aufmerksam sein solltest.
+
+## Teil 1: Schema lesen
+
+Erkläre mit eigenen Worten:
+
+- Warum `tickets.team_id` verpflichtend ist.
+- Warum `tickets.assigned_to_id` optional ist.
+- Warum `ticket_labels` einen zusammengesetzten Primärschlüssel hat.
+- Welche Daten beim Anzeigen einer Ticket-Liste wahrscheinlich gebraucht werden.
+
+## Teil 2: SQL korrigieren
+
+Eine fehlerhafte Query ist ein realistisches Arbeitsmittel. In Projekten liest du oft bestehenden Code und musst entscheiden, ob er fachlich korrekt ist.
+
+Typische Fragen:
+
+- Fehlt eine Join-Bedingung?
+- Werden optionale Beziehungen versehentlich ausgeschlossen?
+- Wird vor oder nach der Gruppierung gefiltert?
+- Ist die Query für den späteren API-Fall verständlich?
+
+## Teil 3: Transaktion skizzieren
+
+Beim Erstellen eines Tickets sollen drei Operationen zusammengehören:
+
+1. Ticket speichern
+2. ersten Kommentar speichern
+3. Event `created` speichern
+
+Wenn Schritt 2 fehlschlägt, muss Schritt 1 zurückgerollt werden. Sonst entsteht ein Ticket ohne Startkommunikation und ohne vollständigen Verlauf. Das ist kein SQL-Detail, sondern eine fachliche Konsistenzregel.
+
+## Teil 4: Zugriffstechnik einordnen
+
+Nicht jeder Datenzugriff braucht dieselbe Technik:
+
+| Situation | Häufig passende Technik |
+| --- | --- |
+| Ein Ticket per ID laden | Repository Method |
+| Offene Tickets eines Teams laden | Repository Method oder JPQL |
+| Reporting über Teams, Status und Priorität | native SQL oder gezielte Projektion |
+| Tickets mit Kommentaren ohne N+1 laden | JPQL mit Fetch-Strategie oder DTO-Projektion |
+
+Die genaue Entscheidung hängt vom Projekt ab. Wichtig ist, dass du sie begründen kannst.

docs/1_review_orientation/3_diagnostic_task.md

@@ -0,0 +1,55 @@
+# Brücke zu Spring Boot, JPA und Flyway
+
+Block 1 endet dort, wo **Database Development** richtig beginnt: bei der Frage, wie Datenbankentscheidungen im Anwendungscode sichtbar werden.
+
+## Vom SQL-Schema zur Anwendung
+
+In einer Spring-Boot-Anwendung treffen mehrere Schichten aufeinander:
+
+```mermaid
+flowchart LR
+    A[HTTP Request] --> B[Controller]
+    B --> C[Service]
+    C --> D[Repository]
+    D --> E[(PostgreSQL)]
+```
+
+Der Controller nimmt Anfragen entgegen. Der Service enthält fachliche Abläufe und Transaktionsgrenzen. Das Repository kapselt den Datenzugriff. PostgreSQL erzwingt Constraints und speichert den Zustand dauerhaft.
+
+Diese Schichten sind nicht einfach Ordner im Projekt. Sie verteilen Verantwortung.
+
+## ORM hilft, ersetzt aber kein Verständnis
+
+Hibernate/JPA kann Entities auf Tabellen abbilden, Beziehungen laden und SQL generieren. Das ist produktiv und in vielen Anwendungen sinnvoll. Gleichzeitig entstehen typische Fragen:
+
+- Wird eine Beziehung zu früh oder zu spät geladen?
+- Entsteht ein N+1-Problem?
+- Passt die Entity-Struktur zur API?
+- Ist eine Query als Repository Method noch lesbar?
+- Braucht ein Reporting-Fall natives SQL?
+
+**Database Development** trainiert genau diese Entscheidungen.
+
+## Migrationen statt zufälliger Schemaänderungen
+
+Im Unterricht wird das Ticket-Schema zuerst als SQL-Schema sichtbar. Später wird es mit Flyway versioniert. Damit wird eine wichtige professionelle Regel eingeführt:
+
+> Das Datenbankschema entwickelt sich kontrolliert mit der Anwendung.
+
+Eine Spalte hinzuzufügen ist einfach. Schwieriger ist die Frage, was mit bestehenden Daten passiert, wann Constraints aktiviert werden und wie ein Team die Änderung nachvollziehen kann.
+
+## Transaktionsgrenzen gehören in den Service
+
+In **Relational Databases** hast du Transaktionen als Datenbankkonzept kennengelernt. In **Database Development** wird daraus eine Architekturentscheidung:
+
+```java
+@Transactional
+public TicketDto createTicket(CreateTicketRequest request) {
+    // Ticket speichern
+    // ersten Kommentar speichern
+    // Event schreiben
+    // bei Fehler: Rollback
+}
+```
+
+Die Annotation ist nur die technische Oberfläche. Entscheidend ist die fachliche Frage: Welche Zustandsänderungen gehören untrennbar zusammen?