# PostgreSQL mit DBeaver über einen SSH-Tunnel

Ein SSH-Tunnel erlaubt den Zugriff auf eine Datenbank, die nur von einer
entfernten VM aus erreichbar ist. Der Tunnel löst dabei nicht automatisch alle
Netzwerkprobleme: Der Zielhost und Zielport werden aus Sicht der VM bewertet.

## Verbindungsweg

```text
DBeaver auf dem eigenen Rechner
        |
        | lokaler Tunnel-Endpunkt
        v
SSH-Client  ───────────────►  SSH-Server auf der VM
                                  |
                                  | Zielhost:Zielport
                                  v
                           PostgreSQL auf der VM
                           oder PostgreSQL-Container
```

Ein möglicher manueller Tunnel sieht so aus:

```bash
ssh -L 15432:127.0.0.1:5432 <user>@<vm-host>
```

Danach ist die Datenbank vom eigenen Rechner aus typischerweise über
`127.0.0.1:15432` erreichbar. Bei DBeaver hängen die genauen Felder von der
verwendeten SSH-Tunnel-Konfiguration ab. Wichtig ist, die lokale
Datenbankadresse nicht mit dem entfernten Ziel der Weiterleitung zu
verwechseln.

## Docker als Datenbank-Host

Wenn PostgreSQL in Docker läuft, gibt es mehrere mögliche Ziele:

| Situation | Typisches Ziel aus Sicht der VM |
| --- | --- |
| PostgreSQL läuft direkt auf der VM | `127.0.0.1:5432` |
| PostgreSQL-Port ist veröffentlicht | `127.0.0.1:<veröffentlichter Port>` |
| Zugriff aus einem anderen Container | Compose-Service-Name, z. B. `postgres:5432` |
| Direkter Zugriff auf einen Container | aktuelle Container-IP, z. B. `172.19.0.2:5432` |

Eine Container-IP sollte nur zum Testen verwendet werden. Sie kann sich nach
dem Neustart oder Neuerstellen des Containers ändern. Für eine dauerhafte
Konfiguration sind ein Compose-Service-Name innerhalb des Docker-Netzwerks
oder ein veröffentlichter Host-Port vorzuziehen.

## Schrittweise Diagnose

### 1. Den aktuellen Container und seine Ports prüfen

Auf der VM:

```bash
docker ps
docker inspect <postgres-container>
sudo ss -ltnp | grep 5432
```

Bei `docker ps` auf die Spalte `PORTS` achten. Eine Ausgabe wie
`127.0.0.1:5432->5432/tcp` bedeutet, dass PostgreSQL auf der VM lokal
veröffentlicht ist. Eine Ausgabe wie `0.0.0.0:15432->5432/tcp` bedeutet, dass
der Host-Port `15432` zum Container-Port `5432` weiterleitet.

### 2. Den Zielendpunkt von der VM aus testen

```bash
nc -vz <zielhost> <zielport>
psql -h <zielhost> -p <zielport> -U <user> -d <database>
```

Diese Tests müssen mit dem Host und Port durchgeführt werden, die der
SSH-Tunnel aus Sicht der VM erreichen soll. Ein funktionierendes `psql` ohne
`-h` kann beispielsweise über einen lokalen Unix-Socket verbinden und sagt
nichts über die TCP-Verbindung aus.

### 3. PostgreSQL-Logs beobachten

```bash
docker logs --tail 100 -f <postgres-container>
```

Dann in DBeaver den Verbindungstest ausführen:

- **Kein neuer Logeintrag:** DBeaver erreicht PostgreSQL nicht. Tunnel,
  Zielhost, Zielport oder lokale/entfernte Portzuordnung prüfen.
- **Eintrag mit Authentifizierungsfehler:** Netzwerkweg funktioniert; Benutzer,
  Passwort, Datenbank oder `pg_hba.conf` prüfen.
- **Verbindung wird sofort beendet:** SSL-Modus, PostgreSQL-Treiber und
  Tunnelziel vergleichen.

## Typische Fehler

### `hostname -I` liefert mehrere Adressen

`hostname -I` zeigt alle Adressen der VM. Dazu können die Azure-Adresse und
mehrere Docker-Bridge-Adressen gehören. Die Ausgabe ist keine Liste von
gleichwertigen Datenbankadressen:

```text
10.2.0.4     VM-Adresse im privaten Azure-Netzwerk
172.19.0.1   Docker-Bridge-Gateway
172.19.0.2   möglicherweise PostgreSQL-Container
```

Mit `docker network inspect <network-name>` lässt sich prüfen, welchem
Container eine Docker-Adresse aktuell zugeordnet ist.

### SSH funktioniert, DBeaver meldet `EOF Exception`

Ein erfolgreicher SSH-Aufbau beweist nur, dass der SSH-Server erreichbar ist.
Der weitergeleitete TCP-Stream kann trotzdem am falschen Ziel oder Port enden.
Prüfen:

1. Welcher lokale Port wird von DBeaver verwendet?
2. Welcher entfernte Host und Port werden durch den Tunnel angesprochen?
3. Ist der PostgreSQL-Container noch unter derselben IP erreichbar?
4. Lauscht PostgreSQL auf TCP und nicht nur auf einem Unix-Socket?
5. Verwendet DBeaver denselben SSL-Modus wie `psql`?
6. Erscheint der Test in den PostgreSQL-Logs?

Die Verbindung sollte zunächst mit einer expliziten TCP-Verbindung geprüft
werden:

```bash
psql -h 127.0.0.1 -p <port> -U <user> -d <database>
```

Dabei muss `<port>` dem tatsächlich veröffentlichten Port oder dem lokalen
Port des SSH-Tunnels entsprechen.

## Sicherheits- und Wartungshinweise

- Keine Passwörter oder produktiven Zugangsdaten in Notizen oder
  Verbindungsdefinitionen im Klartext speichern.
- Container-IPs nicht als langfristige Infrastrukturkonfiguration verwenden.
- Für dauerhafte Zugriffe DNS-Namen, Compose-Service-Namen oder stabile
  Host-Port-Zuordnungen bevorzugen.
- Für einen Diagnosefall die verwendeten Hosts, Ports, SSL-Einstellungen und
  den Verbindungsweg dokumentieren, aber sensible Werte anonymisieren.

Siehe auch [[SSH Verbindung in Linux]], [[psql]] und [[Docker]].