Bienvenue dans le guide de dépannage de HarborDB. Cette ressource complète vous aide à identifier et résoudre rapidement les problèmes les plus courants rencontrés lors de l'utilisation de HarborDB et PostgreSQL. Que vous rencontriez des problèmes de connexion, des performances lentes ou des problèmes d'interface, vous trouverez ici des solutions étape par étape.

Comment utiliser ce guide

Identifiez votre problème parmi les catégories ci-dessous
Suivez les étapes de dépannage dans l'ordre
Essayez les solutions jusqu'à ce que le problème soit résolu
Si toujours non résolu, utilisez la section "Contacter le support"

Référence rapide : Problèmes courants

| Problème | Cause probable | Solution rapide | | ------------------------------ | -------------------------------------- | ------------------------------------------ | | Impossible de se connecter à PostgreSQL | Serveur non démarré, pare-feu bloquant | Démarrez PostgreSQL, vérifiez les paramètres du pare-feu | | Performances de requête lentes | Index manquants, grands ensembles de données | Ajoutez des index, utilisez LIMIT, optimisez les requêtes | | Utilisation élevée de la mémoire | Trop d'onglets ouverts, grands ensembles de résultats | Fermez les onglets inutilisés, activez le mode streaming | | Échec de l'exportation | Problèmes de permissions, disque plein | Vérifiez les permissions des fichiers, libérez de l'espace disque | | Interface semble lente | Contraintes des ressources système | Fermez d'autres applications, redémarrez HarborDB |

Problèmes de connexion

"Impossible de se connecter au serveur PostgreSQL"

Symptômes :

Erreurs de délai d'attente de connexion
Messages "Connexion refusée"
Chargement infini lors du test de connexion

Dépannage étape par étape :

Vérifiez l'état du serveur PostgreSQL :
```
# Dans le Terminal, vérifiez si PostgreSQL est en cours d'exécution
pg_isready -h localhost -p 5432
```
- Si non démarré : brew services start postgresql (Homebrew) ou démarrez via Préférences Système
Vérifiez les détails de la connexion :
- Nom d'hôte : localhost pour local, IP/nom d'hôte correct pour distant
- Port : Par défaut 5432, confirmez votre port PostgreSQL
- Nom de la base de données : Doit exister avant de se connecter
- Nom d'utilisateur/mot de passe : Sensibles à la casse, vérifiez les identifiants
Vérifiez les paramètres du pare-feu :
- Préférences Système → Sécurité et confidentialité → Pare-feu
- Assurez-vous que le port PostgreSQL (5432) est autorisé
- Essayez de désactiver temporairement le pare-feu pour tester

Testez la connectivité réseau :

# Pour les serveurs distants
ping votre-adresse-serveur
telnet votre-adresse-serveur 5432

Solutions courantes :

✅ Démarrez le service PostgreSQL
✅ Nom d'hôte/adresse IP correct(e)
✅ Ouvrez le port 5432 du pare-feu
✅ Utilisez les bonnes identifiants

"Échec de l'authentification par mot de passe"

Causes :

Nom d'utilisateur ou mot de passe incorrect
Incompatibilité de méthode d'authentification PostgreSQL
L'utilisateur n'a pas les permissions sur la base de données

Solutions :

Réinitialisez le mot de passe PostgreSQL :

-- Connectez-vous en tant que superutilisateur (via ligne de commande)
ALTER USER nom_utilisateur WITH PASSWORD 'nouveau_mot_de_passe';

Vérifiez la méthode d'authentification :
- Consultez le fichier pg_hba.conf
- Méthodes courantes : md5, scram-sha-256, trust
- Mettez à jour la méthode si nécessaire, redémarrez PostgreSQL

Vérifiez les permissions de l'utilisateur :

-- Listez les utilisateurs et leurs permissions
\du

-- Listez les bases de données et les accès
\l

Erreurs de connexion SSL/TLS

Lors de la connexion à des serveurs distants :

Vérifiez les exigences SSL :
- Le serveur peut nécessiter un mode SSL spécifique
- Peut nécessiter l'importation d'un certificat
Essayez différents modes SSL dans HarborDB :
- Commencez par prefer
- Puis essayez require
- Enfin verify-full (nécessite un certificat)
Importez les certificats si vous utilisez verify-full :
- Obtenez le certificat de l'administrateur du serveur
- Importez-le dans l'Accès au trousseau macOS
- Accordez l'accès au certificat à HarborDB

Problèmes de performance

Exécution lente des requêtes

Étapes de diagnostic :

Utilisez EXPLAIN pour analyser :
- Cliquez sur le bouton "Explain" (⚡) dans HarborDB
- Cherchez "Seq Scan" (balayage complet de la table) - souvent lent
- Cherchez "Index Scan" - généralement plus rapide

Vérifiez les index manquants :

-- Trouvez les colonnes fréquemment filtrées sans index
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
  );

Ajoutez des index appropriés :

-- Index sur une seule colonne
CREATE INDEX idx_table_column ON table_name(column_name);

-- Index multi-colonnes pour les modèles de requêtes courants
CREATE INDEX idx_table_col1_col2 ON table_name(col1, col2);

Correctifs de performance rapides :

Ajoutez la clause LIMIT aux requêtes exploratoires
Sélectionnez uniquement les colonnes nécessaires (pas SELECT *)
Utilisez des clauses WHERE avec des colonnes indexées
Évitez les fonctions dans les clauses WHERE qui empêchent l'utilisation des index

Utilisation élevée de la mémoire

Symptômes :

HarborDB utilise trop de RAM (vérifiez le Moniteur d'activité)
Le système devient lent
Erreurs "Mémoire insuffisante"

Solutions :

Réduisez la taille du cache des requêtes :
- Préférences → Performance → Cache des requêtes
- Réduisez de 256 Mo par défaut à 128 Mo si la mémoire est limitée
Activez le mode streaming :
- Préférences → Performance → Résultats en streaming
- Activez pour les résultats > 10 000 lignes
- Réduit l'utilisation de la mémoire pour les grands ensembles de données
Gérez les onglets ouverts :
- Fermez les onglets de requête inutilisés
- HarborDB conserve les ensembles de résultats en mémoire par onglet
- Travail régulier : maximum 5-10 onglets
Redémarrez HarborDB :
- Quittez et redémarrez quotidiennement pendant une utilisation intensive
- Efface l'utilisation de mémoire accumulée

L'application semble lente

Correctifs rapides :

Fermez d'autres applications :
- Surtout les applications gourmandes en ressources (Chrome avec beaucoup d'onglets, Docker, etc.)
- Vérifiez la pression mémoire dans le Moniteur d'activité
Réduisez les animations de l'interface :
- Préférences → Apparence → Désactiver les animations
- Expérience plus fluide sur du matériel plus ancien
Simplifiez l'interface :
- Réduisez les sections de la barre latérale non utilisées
- Utilisez un thème de couleur plus simple
- Désactivez la coloration syntaxique pour les très grandes requêtes

Problèmes d'exportation et de fichiers

L'exportation échoue ou crée des fichiers vides

Causes courantes et solutions :

Problèmes de permissions :

# Vérifiez les permissions du dossier
ls -la ~/Desktop/

# Essayez un autre emplacement de sauvegarde
# Utilisez le dossier Documents au lieu du Bureau

Problèmes d'espace disque :

# Vérifiez l'espace disque disponible
df -h

# Nécessite au moins 2x la taille de l'exportation en espace libre

Problèmes de format de fichier :
- CSV : Essayez un délimiteur différent (virgule, point-virgule, tabulation)
- CSV : Ajoutez des qualificateurs de texte (guillemets autour des champs)
- JSON : Essayez les deux formats "Jolie impression" et "Compact"
Optimisation des grandes exportations :
- Exportez en morceaux plus petits
- Utilisez CSV au lieu de JSON pour les grands ensembles de données
- Activez la compression dans les paramètres d'exportation

"Fichier non trouvé" ou exportations manquantes

Vérifiez l'emplacement de sauvegarde par défaut :
- Préférences → Exportation → Emplacement de sauvegarde par défaut
- Changez vers un dossier fréquemment utilisé

Recherchez les fichiers :

# Recherchez les fichiers CSV/JSON récents
find ~ -name "*.csv" -mtime -1
find ~ -name "*.json" -mtime -1

Vérifiez la Corbeille :
- Les exportations ont peut-être été accidentellement supprimées
- Restaurez depuis la Corbeille si trouvé

Problèmes d'interface et d'affichage

Thème non appliqué correctement

Problèmes de mode sombre/clair de macOS :

Vérifiez les paramètres système :
- Paramètres Système → Apparence
- Assurez-vous que "Auto" ou le thème souhaité est sélectionné
Redémarrez HarborDB :
- Quittez complètement (⌘ + Q)
- Rouvrez pour appliquer le thème système
Forcer le thème dans HarborDB :
- Préférences → Apparence → Thème
- Choisissez "Clair", "Sombre" ou "Système"

Fonctionnalités ou menus manquants

Mettez à jour HarborDB :
- Vérifiez les mises à jour (HarborDB → Vérifier les mises à jour)
- App Store → onglet Mises à jour
Réinitialisez la disposition de l'interface :
- Fenêtre → Réinitialiser la disposition
- Restaure l'arrangement des panneaux par défaut
Vérifiez la disponibilité des fonctionnalités :
- Certaines fonctionnalités nécessitent des versions spécifiques de PostgreSQL
- Vérifiez la compatibilité dans la documentation des fonctionnalités

Problèmes d'affichage du texte

Problèmes de taille de police/lisibilité :

Ajustez la taille de police de l'éditeur :
- Préférences → Éditeur → Taille de police
- Augmentez pour une meilleure lisibilité
Utilisez le zoom de macOS :
- Paramètres Système → Accessibilité → Zoom
- Activez pour une magnification temporaire
Mode à contraste élevé :
- Paramètres Système → Accessibilité → Affichage
- Augmentez le contraste pour une meilleure visibilité

Problèmes spécifiques à macOS

Erreur "L'application est endommagée"

Lors de l'ouverture de HarborDB :

# Supprimez l'attribut de quarantaine
sudo xattr -cr /Applications/HarborDB.app

# Rouvrez HarborDB
open /Applications/HarborDB.app

Avertissements Gatekeeper

Pour les téléchargements directs (pas depuis l'App Store) :

Paramètres Système → Confidentialité et sécurité
Faites défiler jusqu'à la section "Sécurité"
Cliquez sur "Ouvrir quand même" à côté de l'avertissement HarborDB
Confirmez l'ouverture

Problèmes d'accès Touch ID/Trousseau

Erreurs "HarborDB souhaite utiliser votre mot de passe" :

Réinitialisez les permissions du Trousseau :
- Ouvrez l'application Accès au trousseau
- Recherchez "HarborDB"
- Supprimez les entrées existantes
- Re-ajoutez la connexion dans HarborDB
Réparation du Trousseau :
- Accès au trousseau → Fichier → Premiers secours du trousseau
- Exécutez la réparation sur le trousseau "Login"

Compatibilité avec les versions de macOS

Minimum : macOS 12.0 (Monterey) Recommandé : macOS 13.0 (Ventura) ou version ultérieure

Vérifiez la compatibilité :

# Vérifiez la version de macOS
sw_vers

# Vérifiez l'architecture (Apple Silicon vs Intel)
uname -m

Problèmes spécifiques aux bases de données

"La relation n'existe pas"

Lors de l'interrogation des tables :

Vérifiez le schéma :

-- Listez toutes les tables dans le schéma actuel
\dt

-- Listez les tables dans tous les schémas
SELECT schemaname, tablename
FROM pg_tables
WHERE tablename LIKE '%votre_table%';

Utilisez des noms qualifiés :

-- Au lieu de : SELECT * FROM users;
-- Utilisez la qualification du schéma :
SELECT * FROM public.users;
SELECT * FROM auth.users;

Définissez le schéma par défaut :
- Modifiez la connexion dans HarborDB
- Définissez "Schéma par défaut" sur le schéma couramment utilisé

Erreurs de permissions sur les objets de base de données

Permission refusée pour la relation

Vérifiez vos permissions :

-- Connectez-vous en tant que superutilisateur ou propriétaire de la table
SELECT grantee, privilege_type
FROM information_schema.role_table_grants
WHERE table_name = 'votre_table';

Demandez des permissions :

-- Exemple : Accordez l'autorisation SELECT
GRANT SELECT ON table_name TO votre_utilisateur;

Gestion des grands ensembles de données

"Mémoire insuffisante" ou extrêmement lent :

Utilisez la pagination côté serveur :

-- Au lieu de : SELECT * FROM huge_table;
-- Utilisez :
SELECT * FROM huge_table LIMIT 1000 OFFSET 0;
-- Puis incrémentez OFFSET pour les pages suivantes

Activez le streaming dans HarborDB :
- Préférences → Performance → Mode streaming
- Définissez un seuil (par exemple, 10 000 lignes)
Utilisez des vues matérialisées pour les requêtes complexes fréquentes

Problèmes de réseau et de connexion à distance

Connexions distantes lentes

Conseils d'optimisation :

Activez la compression :
- Paramètres de connexion → Avancé → Compression
- Réduit la taille du transfert de données
Utilisez le tunneling SSH :
- Plus sécurisé que la connexion directe
- Peut améliorer les performances sur les réseaux restreints
Planifiez les requêtes lourdes :
- Exécutez pendant les heures creuses
- Utilisez la fonction de planificateur de requêtes de HarborDB

Coupures intermittentes de connexion

Augmentez les paramètres de délai d'attente :
- Paramètres de connexion → Délai d'attente
- Augmentez de 30 à 60 secondes
Activez Keep-Alive :
- Paramètres de connexion → Keep-Alive
- Maintient les connexions inactives

Vérifiez la stabilité du réseau :

# Testez la stabilité du réseau
ping -c 100 votre-adresse-serveur
# Cherchez la perte de paquets

Avant de contacter le support

Informations à collecter

Si les problèmes persistent après le dépannage, collectez ces informations :

Informations système :
- Version de macOS (Menu Pomme → À propos de ce Mac)
- Version de HarborDB (HarborDB → À propos de HarborDB)
- Version de PostgreSQL (SELECT version();)
Détails de l'erreur :
- Message d'erreur exact (capture d'écran si possible)
- Étapes pour reproduire le problème
- Quand le problème a commencé
Détails de la configuration :
- Paramètres de connexion (sans mots de passe)
- Requête causant des problèmes (le cas échéant)
- Paramètres d'exportation (si lié à l'exportation)

Outils de diagnostic dans HarborDB

Générez un rapport de diagnostic :
- Aide → Créer un rapport de diagnostic
- Inclut les journaux, configuration, informations système
Consultez les journaux d'application :
- Aide → Afficher les journaux
- Filtrez les messages d'erreur et d'avertissement
Console.app pour les journaux système :
- Ouvrez Console.app
- Recherchez "HarborDB"
- Cherchez les rapports de plantage

Vérification rapide

Avant de contacter le support, vérifiez :

[ ] macOS est à jour
[ ] HarborDB est la dernière version
[ ] Le serveur PostgreSQL est en cours d'exécution
[ ] La connexion réseau est stable
[ ] L'espace disque suffisant est disponible
[ ] L'utilisateur a les permissions nécessaires

Contacter le support

Si vous avez essayé toutes les étapes de dépannage et que le problème persiste :

Support par e-mail : support@harbordb.com
Incluez dans votre e-mail :
- Rapport de diagnostic (depuis le menu Aide)
- Captures d'écran des messages d'erreur
- Étapes pour reproduire le problème
- Quelles étapes de dépannage vous avez essayées
Délai de réponse attendu :
- Réponse initiale : Dans les 24-48 heures
- Heures d'ouverture : Lundi-Vendredi, 9h-17h EST
- Problèmes urgents : Marquez l'e-mail comme "URGENT"

Mesures préventives

Maintenance régulière

Hebdomadaire :

Redémarrez HarborDB pour libérer la mémoire
Effacez les fichiers d'exportation temporaires
Sauvegardez les paramètres de connexion importants

Mensuelle :

Mettez à jour HarborDB et PostgreSQL
Revoyez et optimisez les requêtes lentes
Nettoyez les connexions inutilisées

Meilleures pratiques pour éviter les problèmes

Gestion des connexions :
- Utilisez des noms de connexion significatifs
- Testez régulièrement les connexions
- Supprimez les connexions inutilisées
Développement de requêtes :
- Utilisez toujours LIMIT pendant l'exploration
- Testez avec EXPLAIN avant d'exécuter de grandes requêtes
- Sauvegardez les requêtes complexes pour une réutilisation
Maintenance système :
- Gardez macOS à jour
- Sauvegardes régulières Time Machine
- Surveillez l'espace disque

Ressources supplémentaires

FAQ HarborDB - Réponses aux questions courantes
Guide de prise en main - Installation et configuration
Optimisation des performances - Réglage avancé
Guide de sécurité macOS - Meilleures pratiques de sécurité

Problèmes Courants et Dépannage