Datenbank-Konfiguration¶

calServer v2 unterstützt drei Datenbank-Backends: PostgreSQL, MySQL und Microsoft SQL Server. Diese Seite dokumentiert, welche Docker-Compose- und .env-Variablen die Datenbankverbindungen steuern.

Übersicht der Verbindungen¶

┌─────────────────────────────────────────────────────────────┐
│                    Laravel 13 (API v2)                       │
│                                                             │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │    pgsql     │  │ mysql_legacy │  │      sqlsrv       │  │
│  │  (default)   │  │ (Übernahme)  │  │  (MET/TEAM etc.)  │  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬──────────┘  │
└─────────┼────────────────┼───────────────────┼──────────────┘
          │                │                   │
          ▼                ▼                   ▼
  ┌──────────────┐ ┌──────────────┐  ┌─────────────────┐
  │ PostgreSQL 16│ │   MySQL 5.7  │  │  MS SQL Server   │
  │ (V2 eigene)  │ │  (V1, alt)   │  │    2019+         │
  └──────────────┘ └──────────────┘  └─────────────────┘

Connection-Name	Treiber	Zweck	Konfiguriert in
`pgsql`	PostgreSQL	V2-Hauptdatenbank (ADR-008), neue Tabellen	`DB_*` Variablen
`mysql_legacy`	MySQL	V1-Datenbank, nur für die Datenübernahme	`DB_MYSQL_*` Variablen
`mysql`	MySQL	Generische MySQL-Verbindung	`DB_*` Variablen
`sqlsrv`	SQL Server	Externe Systeme (MET/TEAM, Fluke)	`DB_*` Variablen
`sqlite`	SQLite	Nur für lokale Tests (`:memory:`)	`DB_DATABASE`

Die Standard-Verbindung wird über DB_CONNECTION gesetzt (Default: pgsql).

Docker-Compose-Dateien¶

`docker-compose.v2.yml` — V2-Services¶

Zusammen mit docker-compose.v2-standalone.yml (Reverse Proxy, report-runner) der komplette Stack:

docker compose -f docker-compose.v2.yml -f docker-compose.v2-standalone.yml up -d

Service	Image	Port	Zweck
`calserver-postgres`	`postgres:16-alpine`	5432	V2-Datenbank (ADR-008)
`calserver-api-v2`	`calhelp/calserver-api-v2`	8081	Laravel API
`calserver-frontend`	`calhelp/calserver-frontend`	3000	Nuxt 4 Frontend
`redis`	`redis:8-alpine`	6379	Cache, Queue, Sessions

PostgreSQL-Variablen (aus docker/.env):

PG_DATABASE=calserver_v2        # Default: calserver_v2
PG_USERNAME=calserver           # Default: calserver
PG_PASSWORD=                    # PFLICHT – muss gesetzt werden

PG_PASSWORD ist Pflicht

docker-compose.v2.yml erzwingt PG_PASSWORD über ${PG_PASSWORD:?PG_PASSWORD is required}. Ohne diesen Wert startet der Container nicht.

Environment-Variablen im Detail¶

V2-Hauptverbindung (PostgreSQL)¶

Diese Variablen steuern die Standard-Verbindung (DB_CONNECTION=pgsql):

Variable	Default	Beschreibung
`DB_CONNECTION`	`pgsql`	Aktiver Treiber: `pgsql`, `mysql`, `sqlsrv`, `sqlite`
`DB_HOST`	`127.0.0.1`	Datenbankserver (Docker: `calserver-postgres`)
`DB_PORT`	`5432`	Port
`DB_DATABASE`	`calserver_v2`	Datenbankname
`DB_USERNAME`	`calserver`	Benutzer
`DB_PASSWORD`	(leer)	Passwort

V1-Datenbank für die Datenübernahme (MySQL)¶

Nur nötig beim Umstieg von v1. Variablen mit DB_MYSQL_-Prefix für die mysql_legacy-Connection:

Variable	Fallback	Beschreibung
`DB_MYSQL_HOST`	`DB_HOST`	MySQL-Server (Docker: `mysql_db`)
`DB_MYSQL_PORT`	`3306`	Port
`DB_MYSQL_DATABASE`	`DB_DATABASE`	V1-Datenbankname
`DB_MYSQL_USERNAME`	`DB_USERNAME`	Benutzer
`DB_MYSQL_PASSWORD`	`DB_PASSWORD`	Passwort
`DB_PREFIX`	(leer)	Nur für Altinstallationen mit Tabellen-Präfix

Fallback-Verhalten

Wenn keine DB_MYSQL_*-Variable gesetzt ist, fällt die mysql_legacy-Connection auf die generischen DB_*-Werte zurück. Das vereinfacht Setups mit nur einer MySQL-Instanz.

SQL Server (optional)¶

Variable	Default	Beschreibung
`DB_HOST`	`localhost`	SQL-Server-Host
`DB_PORT`	`1433`	Port
`DB_DATABASE`	`laravel`	Datenbankname
`DB_USERNAME`	`root`	Benutzer
`DB_PASSWORD`	(leer)	Passwort

SQL Server teilt DB_*-Variablen

SQL Server nutzt dieselben DB_*-Variablen wie PostgreSQL. Wird DB_CONNECTION=sqlsrv gesetzt, interpretiert Laravel die generischen Variablen für SQL Server.

Umgebungs-Profiles¶

Lokale Entwicklung (`laravel/.env.example`)¶

# V2 PostgreSQL (default)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=calserver_v2
DB_USERNAME=calserver
DB_PASSWORD=

# V1 MySQL (nur für die Datenübernahme)
DB_MYSQL_HOST=127.0.0.1
DB_MYSQL_PORT=3306
DB_MYSQL_DATABASE=calhelp
DB_MYSQL_USERNAME=calhelp
DB_MYSQL_PASSWORD=
DB_PREFIX=

Docker-Produktion (`docker-compose.v2.yml`)¶

# PostgreSQL (über Container-Netzwerk)
DB_CONNECTION=pgsql
DB_HOST=calserver-postgres
DB_PORT=5432
DB_DATABASE=${PG_DATABASE:-calserver_v2}
DB_USERNAME=${PG_USERNAME:-calserver}
DB_PASSWORD=${PG_PASSWORD}

Unit-Tests (`laravel/.env.testing`)¶

DB_CONNECTION=sqlite
DB_DATABASE=:memory:

SQLite In-Memory für schnelle, isolierte Tests. Keine externe DB nötig.

CI/CD-Tests (`laravel/.env.ci`)¶

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=calserver_v2_test
DB_USERNAME=calserver
DB_PASSWORD=ci_test_password

PostgreSQL-Instanz in der CI-Pipeline für realitätsnahe Tests.

Verbindungsauswahl nach Szenario¶

Szenario	`DB_CONNECTION`	Zusätzliche Verbindung
Standard-Deployment	`pgsql`	—
Umstieg von v1 (Datenübernahme)	`pgsql`	`mysql_legacy`
Vorhandene MySQL-Instanz	`mysql`	—
Vorhandener SQL Server	`sqlsrv`	—
MET/TEAM-Integration	`pgsql`	`sqlsrv`
Lokale Tests	`sqlite`	—
CI-Pipeline	`pgsql`	—

Referenz: `config/database.php`¶

Die Laravel-Konfiguration definiert alle Verbindungen in laravel/config/database.php:

'default' => env('DB_CONNECTION', 'pgsql'),

'connections' => [
    'sqlite'       => [ /* ... */ ],
    'mysql'        => [ /* ... charset: utf8mb4 */ ],
    'mariadb'      => [ /* ... charset: utf8mb4 */ ],
    'pgsql'        => [ /* ... search_path: public, sslmode: prefer */ ],
    'mysql_legacy' => [ /* ... DB_MYSQL_* mit Fallback auf DB_* */ ],
    'sqlsrv'       => [ /* ... charset: utf8 */ ],
],

Vollständige Datei: laravel/config/database.php

Abstraktionsregeln¶

Alle DB-Zugriffe müssen DB-agnostisch sein (siehe CLAUDE.md):

Eloquent & Query Builder — kein direktes PDO
DbDialect-Helper für unvermeidliches Raw SQL (app/Support/DbDialect.php)
Migrations nur über Schema Builder, kein rohes DDL
Repository-Pattern für treiberspezifische Syntax (Volltextsuche, JSON, CTEs)
Keine DB-spezifischen Typen in Migrations (kein ENUM, SERIAL, JSONB)
Frontend macht keine DB-Annahmen — API ist das einzige Interface