Häufige Probleme & Fehlerbehebung

Willkommen zum HarborDB-Fehlerbehebungsleitfaden. Diese umfassende Ressource hilft Ihnen, die häufigsten Probleme bei der Arbeit mit HarborDB und PostgreSQL schnell zu identifizieren und zu beheben. Egal, ob Sie Verbindungsprobleme, langsame Leistung oder Oberflächenprobleme haben – hier finden Sie Schritt-für-Schritt-Lösungen.

Wie Sie diesen Leitfaden verwenden

1. Identifizieren Sie Ihr Problem aus den unten stehenden Kategorien
2. Folgen Sie den Fehlerbehebungsschritten in der angegebenen Reihenfolge
3. Probieren Sie die Lösungen aus, bis das Problem gelöst ist
4. Wenn es immer noch nicht gelöst ist, verwenden Sie den Abschnitt "Support kontaktieren"

Kurzreferenz: Häufige Probleme

| Problem | Wahrscheinliche Ursache | Schnelle Lösung | | ----------------------------- | ----------------------------------------------- | ------------------------------------------ | | Kann keine Verbindung zu PostgreSQL herstellen | Server läuft nicht, Firewall blockiert | PostgreSQL starten, Firewall-Einstellungen prüfen | | Langsame Abfrageleistung | Fehlende Indizes, große Datensätze | Indizes hinzufügen, LIMIT verwenden, Abfragen optimieren | | Hohe Speichernutzung | Zu viele geöffnete Tabs, große Ergebnismengen | Unbenutzte Tabs schließen, Streaming-Modus aktivieren | | Export fehlgeschlagen | Berechtigungsprobleme, Festplatte voll | Dateiberechtigungen prüfen, Speicherplatz freigeben | | Oberfläche fühlt sich träge an | Systemressourcenbeschränkungen | Andere Apps schließen, HarborDB neu starten |

Verbindungsprobleme

"Kann keine Verbindung zum PostgreSQL-Server herstellen"

Symptome:

• Verbindungs-Timeout-Fehler
• "Verbindung abgelehnt"-Meldungen
• Endloses Laden beim Testen der Verbindung

Schritt-für-Schritt-Fehlerbehebung:

1. PostgreSQL-Serverstatus prüfen:

   # Im Terminal prüfen, ob PostgreSQL läuft
   pg_isready -h localhost -p 5432
   

   • Falls nicht läuft: brew services start postgresql (Homebrew) oder über Systemeinstellungen starten

2. Verbindungsdetails überprüfen:

   • Hostname: localhost für lokal, korrekte IP/Hostname für Remote
   • Port: Standard ist 5432, Ihren PostgreSQL-Port bestätigen
   • Datenbankname: Muss existieren, bevor Sie eine Verbindung herstellen
   • Benutzername/Passwort: Groß-/Kleinschreibung beachten, Anmeldedaten prüfen

3. Firewall-Einstellungen prüfen:

   • Systemeinstellungen → Sicherheit & Datenschutz → Firewall
   • Sicherstellen, dass PostgreSQL-Port (5432) erlaubt ist
   • Firewall vorübergehend zum Testen deaktivieren

4. Netzwerkverbindung testen:

   # Für Remote-Server
   ping Ihre-Server-Adresse
   telnet Ihre-Server-Adresse 5432
   

Häufige Lösungen:

• ✅ PostgreSQL-Dienst starten
• ✅ Korrekter Hostname/IP-Adresse
• ✅ Firewall-Port 5432 öffnen
• ✅ Korrekte Anmeldedaten verwenden

"Passwort-Authentifizierung fehlgeschlagen"

Ursachen:

• Falscher Benutzername oder Passwort
• PostgreSQL-Authentifizierungsmethode stimmt nicht überein
• Benutzer hat keine Datenbankberechtigungen

Lösungen:

1. PostgreSQL-Passwort zurücksetzen:

   -- Als Superuser verbinden (über Befehlszeile)
   ALTER USER benutzername WITH PASSWORD 'neues_passwort';
   

2. Authentifizierungsmethode prüfen:

   • Datei pg_hba.conf anzeigen
   • Häufige Methoden: md5, scram-sha-256, trust
   • Bei Bedarf Methode aktualisieren, PostgreSQL neu starten

3. Benutzerberechtigungen überprüfen:

   -- Benutzer und Berechtigungen auflisten
   \du
   
   -- Datenbanken und Zugriff auflisten
   \l
   

SSL/TLS-Verbindungsfehler

Bei der Verbindung zu Remote-Servern:

1. SSL-Anforderungen prüfen:

   • Server benötigt möglicherweise bestimmten SSL-Modus
   • Möglicherweise Zertifikatimport erforderlich

2. Verschiedene SSL-Modi in HarborDB ausprobieren:

   • Beginnen Sie mit prefer
   • Dann require versuchen
   • Schließlich verify-full (erfordert Zertifikat)

3. Zertifikate importieren, wenn verify-full verwendet wird:

   • Zertifikat vom Serveradministrator erhalten
   • In macOS Keychain-Zugriff importieren
   • HarborDB-Zugriff auf Zertifikat gewähren

Leistungsprobleme

Langsame Abfrageausführung

Diagnoseschritte:

1. EXPLAIN zur Analyse verwenden:

   • "Erklären"-Button (⚡) in HarborDB anklicken
   • Nach "Seq Scan" (vollständiger Tabellenscan) suchen – oft langsam
   • Nach "Index Scan" suchen – normalerweise schneller

2. Auf fehlende Indizes prüfen:

   -- Häufig gefilterte Spalten ohne Indizes finden
   SELECT schemaname, tablename, attname
   FROM pg_stats
   WHERE schemaname NOT LIKE 'pg_%'
     AND n_distinct > 100
     AND attname NOT IN (
       SELECT column_name
       FROM information_schema.columns
       WHERE table_schema = schemaname
         AND table_name = tablename
     );
   

3. Geeignete Indizes hinzufügen:

   -- Einzelspalten-Index
   CREATE INDEX idx_tabelle_spalte ON tabellenname(spaltenname);
   
   -- Mehrspalten-Index für häufige Abfragemuster
   CREATE INDEX idx_tabelle_spalte1_spalte2 ON tabellenname(spalte1, spalte2);
   

Schnelle Leistungsverbesserungen:

• LIMIT-Klausel zu Erkundungsabfragen hinzufügen
• Nur benötigte Spalten auswählen (nicht SELECT *)
• WHERE-Klauseln mit indizierten Spalten verwenden
• Vermeiden Sie Funktionen in WHERE-Klauseln, die Indexnutzung verhindern

Hohe Speichernutzung

Symptome:

• HarborDB verwendet übermäßig RAM (Aktivitätsanzeige prüfen)
• System wird träge
• "Speicher voll"-Fehler

Lösungen:

1. Abfrage-Cache-Größe reduzieren:

   • Einstellungen → Leistung → Abfrage-Cache
   • Bei Speicherbeschränkung von Standard 256MB auf 128MB reduzieren

2. Streaming-Modus aktivieren:

   • Einstellungen → Leistung → Streaming-Ergebnisse
   • Für Ergebnisse > 10.000 Zeilen aktivieren
   • Reduziert Speichernutzung bei großen Datensätzen

3. Geöffnete Tabs verwalten:

   • Unbenutzte Abfrage-Tabs schließen
   • HarborDB behält Ergebnismengen pro Tab im Speicher
   • Regelmäßige Arbeit: Maximum 5-10 Tabs

4. HarborDB neu starten:

   • Täglich bei intensiver Nutzung beenden und neu starten
   • Beseitigt akkumulierte Speichernutzung

Anwendung fühlt sich träge an

Schnelle Lösungen:

1. Andere Anwendungen schließen:

   • Insbesondere ressourcenintensive Apps (Chrome mit vielen Tabs, Docker usw.)
   • Aktivitätsanzeige auf Speicherdruck prüfen

2. UI-Animationen reduzieren:

   • Einstellungen → Erscheinungsbild → Animationen deaktivieren
   • Glattere Erfahrung auf älterer Hardware

3. Oberfläche vereinfachen:

   • Nicht verwendete Seitenleistenabschnitte einklappen
   • Einfarbiges Farbschema verwenden
   • Syntaxhervorhebung für sehr große Abfragen deaktivieren

Export- und Dateiprobleme

Export fehlgeschlagen oder erstellt leere Dateien

Häufige Ursachen und Lösungen:

1. Berechtigungsprobleme:

   # Ordnerberechtigungen prüfen
   ls -la ~/Desktop/
   
   # Anderen Speicherort ausprobieren
   # Dokumente-Ordner statt Desktop verwenden
   

2. Speicherplatzprobleme:

   # Verfügbaren Speicherplatz prüfen
   df -h
   
   # Mindestens 2x Exportgröße frei benötigt
   

3. Dateiformatprobleme:

   • CSV: Unterschiedliches Trennzeichen probieren (Komma, Semikolon, Tabulator)
   • CSV: Textqualifizierer hinzufügen (Anführungszeichen um Felder)
   • JSON: Sowohl "Pretty" als auch "Compact"-Formate probieren

4. Optimierung großer Exporte:

   • In kleineren Teilen exportieren
   • CSV statt JSON für große Datensätze verwenden
   • Kompression in Exporteinstellungen aktivieren

"Datei nicht gefunden" oder fehlende Exporte

1. Standard-Speicherort prüfen:

   • Einstellungen → Export → Standard-Speicherort
   • In häufig genutzten Ordner ändern

2. Nach Dateien suchen:

   # Nach neueren CSV/JSON-Dateien suchen
   find ~ -name "*.csv" -mtime -1
   find ~ -name "*.json" -mtime -1
   

3. Papierkorb prüfen:

   • Exporte könnten versehentlich gelöscht worden sein
   • Aus Papierkorb wiederherstellen, falls gefunden

Oberflächen- und Anzeigeprobleme

Theme wird nicht korrekt angewendet

macOS Dunkel-/Hellmodus-Probleme:

1. Systemeinstellungen prüfen:

   • Systemeinstellungen → Erscheinungsbild
   • Sicherstellen, dass "Auto" oder gewünschtes Theme ausgewählt ist

2. HarborDB neu starten:

   • Vollständig beenden (⌘ + Q)
   • Neu öffnen, um System-Theme anzuwenden

3. Theme in HarborDB erzwingen:

   • Einstellungen → Erscheinungsbild → Theme
   • "Hell", "Dunkel" oder "System" wählen

Fehlende Funktionen oder Menüs

1. HarborDB aktualisieren:

   • Auf Updates prüfen (HarborDB → Auf Updates prüfen)
   • App Store → Updates-Tab

2. Oberflächen-Layout zurücksetzen:

   • Fenster → Layout zurücksetzen
   • Stellt Standard-Panel-Anordnung wieder her

3. Funktionsverfügbarkeit prüfen:

   • Einige Funktionen erfordern bestimmte PostgreSQL-Versionen
   • Kompatibilität in der Funktionsdokumentation überprüfen

Textanzeigeprobleme

Schriftgröße/Lesbarkeitsprobleme:

1. Editor-Schriftgröße anpassen:

   • Einstellungen → Editor → Schriftgröße
   • Für bessere Lesbarkeit erhöhen

2. macOS-Zoom verwenden:

   • Systemeinstellungen → Barrierefreiheit → Zoom
   • Für temporäre Vergrößerung aktivieren

3. Hoher Kontrastmodus:

   • Systemeinstellungen → Barrierefreiheit → Anzeige
   • Kontrast für bessere Sichtbarkeit erhöhen

macOS-spezifische Probleme

"App ist beschädigt"-Fehler

Beim Öffnen von HarborDB:

# Quarantäne-Attribut entfernen
sudo xattr -cr /Applications/HarborDB.app

# HarborDB erneut öffnen
open /Applications/HarborDB.app

Gatekeeper-Warnungen

Für direkte Downloads (nicht App Store):

1. Systemeinstellungen → Datenschutz & Sicherheit
2. Zum Abschnitt "Sicherheit" scrollen
3. Neben HarborDB-Warnung auf "Trotzdem öffnen" klicken
4. Öffnen bestätigen

Touch ID/Keychain-Zugriffsprobleme

"HarborDB möchte Ihr Passwort verwenden"-Fehler:

1. Keychain-Berechtigungen zurücksetzen:

   • Keychain-Zugriff-App öffnen
   • Nach "HarborDB" suchen
   • Vorhandene Einträge löschen
   • Verbindung in HarborDB neu hinzufügen

2. Keychain reparieren:

   • Keychain-Zugriff → Ablage → Keychain First Aid
   • Reparatur für "Login"-Keychain ausführen

Kompatibilität mit macOS-Versionen

Minimum: macOS 12.0 (Monterey) Empfohlen: macOS 13.0 (Ventura) oder neuer

Kompatibilität prüfen:

# macOS-Version prüfen
sw_vers

# Architektur prüfen (Apple Silicon vs Intel)
uname -m

Datenbankspezifische Probleme

"Relation existiert nicht"

Beim Abfragen von Tabellen:

1. Schema prüfen:

   -- Alle Tabellen im aktuellen Schema auflisten
   \dt
   
   -- Tabellen in allen Schemas auflisten
   SELECT schemaname, tablename
   FROM pg_tables
   WHERE tablename LIKE '%ihre_tabelle%';
   

2. Qualifizierte Namen verwenden:

   -- Anstatt: SELECT * FROM benutzer;
   -- Schema-Qualifikation verwenden:
   SELECT * FROM public.benutzer;
   SELECT * FROM auth.benutzer;
   

3. Standard-Schema setzen:

   • Verbindung in HarborDB bearbeiten
   • "Standard-Schema" auf häufig verwendetes Schema setzen

Berechtigungsfehler bei Datenbankobjekten

Berechtigung für Relation verweigert

1. Ihre Berechtigungen prüfen:

   -- Als Superuser oder Tabellenbesitzer verbinden
   SELECT grantee, privilege_type
   FROM information_schema.role_table_grants
   WHERE table_name = 'ihre_tabelle';
   

2. Berechtigungen anfordern:

   -- Beispiel: SELECT-Berechtigung gewähren
   GRANT SELECT ON tabellenname TO ihr_benutzername;
   

Umgang mit großen Datensätzen

"Speicher voll" oder extrem langsam:

1. Serverseitige Paginierung verwenden:

   -- Anstatt: SELECT * FROM riesige_tabelle;
   -- Verwenden:
   SELECT * FROM riesige_tabelle LIMIT 1000 OFFSET 0;
   -- Dann OFFSET für nächste Seiten erhöhen
   

2. Streaming in HarborDB aktivieren:

   • Einstellungen → Leistung → Streaming-Modus
   • Schwellenwert setzen (z.B. 10.000 Zeilen)

3. Materialisierte Views für häufige komplexe Abfragen verwenden

Netzwerk- und Remote-Verbindungsprobleme

Langsame Remote-Verbindungen

Optimierungstipps:

1. Kompression aktivieren:

   • Verbindungseinstellungen → Erweitert → Kompression
   • Reduziert Datenübertragungsgröße

2. SSH-Tunneling verwenden:

   • Sicherer als direkte Verbindung
   • Kann Leistung in eingeschränkten Netzwerken verbessern

3. Schwere Abfragen planen:

   • Außerhalb der Hauptverkehrszeiten ausführen
   • HarborDBs Abfrageplaner-Funktion verwenden

Unterbrochene Verbindungsabbrüche

1. Timeout-Einstellungen erhöhen:

   • Verbindungseinstellungen → Timeout
   • Von 30 auf 60 Sekunden erhöhen

2. Keep-Alive aktivieren:

   • Verbindungseinstellungen → Keep-Alive
   • Erhält inaktive Verbindungen

3. Netzwerkstabilität prüfen:

   # Netzwerkstabilität testen
   ping -c 100 Ihre-Server-Adresse
   # Nach Paketverlust suchen
   

Bevor Sie den Support kontaktieren

Informationen sammeln

Wenn Probleme nach der Fehlerbehebung bestehen bleiben, sammeln Sie diese Informationen:

1. Systeminformationen:

   • macOS-Version (Apfel-Menü → Über diesen Mac)
   • HarborDB-Version (HarborDB → Über HarborDB)
   • PostgreSQL-Version (SELECT version();)

2. Fehlerdetails:

   • Genaue Fehlermeldung (Screenshot falls möglich)
   • Schritte zur Reproduktion des Problems
   • Wann das Problem begann

3. Konfigurationsdetails:

   • Verbindungseinstellungen (ohne Passwörter)
   • Verursachende Abfrage (falls zutreffend)
   • Exporteinstellungen (falls exportbezogen)

Diagnosetools in HarborDB

1. Diagnosebericht generieren:

   • Hilfe → Diagnosebericht erstellen
   • Enthält Protokolle, Konfiguration, Systeminfo

2. Anwendungsprotokolle anzeigen:

   • Hilfe → Protokolle anzeigen
   • Nach Fehler- und Warnmeldungen filtern

3. Console.app für Systemprotokolle:

   • Console.app öffnen
   • Nach "HarborDB" suchen
   • Nach Absturzberichten suchen

Schnelle Selbstprüfung

Bevor Sie den Support kontaktieren, überprüfen Sie:

• [ ] macOS ist auf dem neuesten Stand
• [ ] HarborDB ist die neueste Version
• [ ] PostgreSQL-Server läuft
• [ ] Netzwerkverbindung ist stabil
• [ ] Ausreichend Speicherplatz verfügbar
• [ ] Benutzer hat notwendige Berechtigungen

Support kontaktieren

Wenn Sie alle Fehlerbehebungsschritte versucht haben und das Problem weiterhin besteht:

1. E-Mail-Support: support@harbordb.com

2. In Ihrer E-Mail enthalten:

   • Diagnosebericht (aus dem Hilfemenü)
   • Screenshots von Fehlermeldungen
   • Schritte zur Reproduktion des Problems
   • Welche Fehlerbehebungsschritte Sie versucht haben

3. Erwartete Antwortzeit:

   • Erste Antwort: Innerhalb von 24-48 Stunden
   • Geschäftszeiten: Montag-Freitag, 9-17 Uhr EST
   • Dringende Probleme: E-Mail als "DRINGEND" markieren

Vorbeugende Maßnahmen

Regelmäßige Wartung

Wöchentlich:

• HarborDB neu starten, um Speicher zu löschen
• Temporäre Exportdateien löschen
• Wichtige Verbindungseinstellungen sichern

Monatlich:

• HarborDB und PostgreSQL aktualisieren
• Langsame Abfragen überprüfen und optimieren
• Ungenutzte Verbindungen bereinigen

Best Practices zur Vermeidung von Problemen

1. Verbindungsverwaltung:

   • Aussagekräftige Verbindungsnamen verwenden
   • Regelmäßig Verbindungen testen
   • Ungenutzte Verbindungen entfernen

2. Abfrageentwicklung:

   • Während der Erkundung immer LIMIT verwenden
   • Mit EXPLAIN testen, bevor große Abfragen ausgeführt werden
   • Komplexe Abfragen zur Wiederverwendung speichern

3. Systemwartung:

   • macOS auf dem neuesten Stand halten
   • Regelmäßige Time Machine-Backups
   • Speicherplatz überwachen

Zusätzliche Ressourcen

• HarborDB FAQ – Antworten auf häufig gestellte Fragen
• Erste-Schritte-Leitfaden – Installation und Einrichtung
• Leistungsoptimierung – Erweiterte Optimierung
• macOS-Sicherheitsleitfaden – Sicherheits-Best Practices