Problemas Comunes y Solución de Problemas

Bienvenido a la guía de solución de problemas de HarborDB. Este recurso integral le ayuda a identificar y resolver rápidamente los problemas más comunes encontrados al trabajar con HarborDB y PostgreSQL. Ya sea que experimente problemas de conexión, rendimiento lento o problemas de interfaz, encontrará soluciones paso a paso aquí.

Cómo Usar Esta Guía

1. Identifique su problema de las categorías a continuación
2. Siga los pasos de solución de problemas en orden
3. Pruebe las soluciones hasta que el problema se resuelva
4. Si aún no se resuelve, use la sección "Contactar al Soporte"

Referencia Rápida: Problemas Comunes

| Problema | Causa Probable | Solución Rápida | | ------------------------------ | --------------------------------------- | ------------------------------------------ | | No puede conectarse a PostgreSQL | Servidor no ejecutándose, firewall bloqueando | Iniciar PostgreSQL, verificar configuración del firewall | | Rendimiento lento de consultas | Índices faltantes, conjuntos de datos grandes | Agregar índices, usar LIMIT, optimizar consultas | | Uso elevado de memoria | Demasiadas pestañas abiertas, conjuntos de resultados grandes | Cerrar pestañas no utilizadas, habilitar modo de transmisión | | Falla la exportación | Problemas de permisos, disco lleno | Verificar permisos de archivo, liberar espacio en disco | | La interfaz se siente lenta | Limitaciones de recursos del sistema | Cerrar otras aplicaciones, reiniciar HarborDB |

Problemas de Conexión

"No se puede conectar al servidor PostgreSQL"

Síntomas:

• Errores de tiempo de espera de conexión
• Mensajes "Conexión rechazada"
• Carga infinita al probar conexión

Solución de Problemas Paso a Paso:

1. Verificar Estado del Servidor PostgreSQL:

   # En Terminal, verificar si PostgreSQL está ejecutándose
   pg_isready -h localhost -p 5432
   

   • Si no está ejecutándose: brew services start postgresql (Homebrew) o iniciar vía Preferencias del Sistema

2. Verificar Detalles de Conexión:

   • Nombre de host: localhost para local, IP/nombre de host correcto para remoto
   • Puerto: Predeterminado es 5432, confirmar su puerto PostgreSQL
   • Nombre de base de datos: Debe existir antes de conectar
   • Nombre de usuario/contraseña: Sensible a mayúsculas, verificar credenciales

3. Verificar Configuración del Firewall:

   • Preferencias del Sistema → Seguridad y Privacidad → Firewall
   • Asegurarse que el puerto PostgreSQL (5432) está permitido
   • Intentar deshabilitar temporalmente el firewall para pruebas

4. Probar Conectividad de Red:

   # Para servidores remotos
   ping su-dirección-servidor
   telnet su-dirección-servidor 5432
   

Soluciones Comunes:

• ✅ Iniciar servicio PostgreSQL
• ✅ Corregir nombre de host/dirección IP
• ✅ Abrir puerto del firewall 5432
• ✅ Usar credenciales correctas

"Falló la autenticación de contraseña"

Causas:

• Nombre de usuario o contraseña incorrectos
• Incompatibilidad del método de autenticación PostgreSQL
• Usuario carece de permisos de base de datos

Soluciones:

1. Restablecer Contraseña PostgreSQL:

   -- Conectarse como superusuario (vía línea de comandos)
   ALTER USER nombre_usuario WITH PASSWORD 'nueva_contraseña';
   

2. Verificar Método de Autenticación:

   • Ver archivo pg_hba.conf
   • Métodos comunes: md5, scram-sha-256, trust
   • Actualizar método si es necesario, reiniciar PostgreSQL

3. Verificar Permisos de Usuario:

   -- Listar usuarios y permisos
   \du
   
   -- Listar bases de datos y acceso
   \l
   

Errores de Conexión SSL/TLS

Al conectar a servidores remotos:

1. Verificar Requisitos SSL:

   • El servidor puede requerir modo SSL específico
   • Puede necesitar importación de certificado

2. Probar Diferentes Modos SSL en HarborDB:

   • Comenzar con preferir
   • Luego probar requerir
   • Finalmente verificar-completo (requiere certificado)

3. Importar Certificados si usa verificar-completo:

   • Obtener certificado del administrador del servidor
   • Importar al Acceso a Keychain de macOS
   • Otorgar acceso de HarborDB al certificado

Problemas de Rendimiento

Ejecución Lenta de Consultas

Pasos de Diagnóstico:

1. Usar EXPLAIN para Analizar:

   • Hacer clic en botón "Explicar" (⚡) en HarborDB
   • Buscar "Secuencia de Escaneo" (escaneo completo de tabla) - a menudo lento
   • Buscar "Escaneo de Índice" - usualmente más rápido

2. Verificar Índices Faltantes:

   -- Encontrar columnas filtradas frecuentemente sin índices
   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. Agregar Índices Apropiados:

   -- Índice de columna única
   CREATE INDEX idx_tabla_columna ON nombre_tabla(nombre_columna);
   
   -- Índice multi-columna para patrones de consulta comunes
   CREATE INDEX idx_tabla_col1_col2 ON nombre_tabla(col1, col2);
   

Soluciones Rápidas de Rendimiento:

• Agregar cláusula LIMIT a consultas exploratorias
• Seleccionar solo columnas necesarias (no SELECT *)
• Usar cláusulas WHERE con columnas indexadas
• Evitar funciones en cláusulas WHERE que impidan uso de índices

Uso Elevado de Memoria

Síntomas:

• HarborDB usa RAM excesiva (verificar Monitor de Actividad)
• El sistema se vuelve lento
• Errores "Sin memoria"

Soluciones:

1. Reducir Tamaño de Caché de Consultas:

   • Preferencias → Rendimiento → Caché de Consultas
   • Reducir de predeterminado 256MB a 128MB si hay limitación de memoria

2. Habilitar Modo de Transmisión:

   • Preferencias → Rendimiento → Transmisión de Resultados
   • Habilitar para resultados > 10,000 filas
   • Reduce uso de memoria para conjuntos de datos grandes

3. Gestionar Pestañas Abiertas:

   • Cerrar pestañas de consulta no utilizadas
   • HarborDB mantiene conjuntos de resultados en memoria por pestaña
   • Trabajo regular: máximo 5-10 pestañas

4. Reiniciar HarborDB:

   • Salir y reiniciar diariamente durante uso intensivo
   • Limpia uso de memoria acumulado

La Aplicación se Siente Lenta

Soluciones Rápidas:

1. Cerrar Otras Aplicaciones:

   • Especialmente aplicaciones intensivas en recursos (Chrome con muchas pestañas, Docker, etc.)
   • Verificar Monitor de Actividad para presión de memoria

2. Reducir Animaciones de Interfaz:

   • Preferencias → Apariencia → Deshabilitar animaciones
   • Experiencia más suave en hardware antiguo

3. Simplificar Interfaz:

   • Contraer secciones de barra lateral no en uso
   • Usar tema de color más simple
   • Deshabilitar resaltado de sintaxis para consultas muy grandes

Problemas de Exportación y Archivos

Falla la Exportación o Crea Archivos Vacíos

Causas y Soluciones Comunes:

1. Problemas de Permisos:

   # Verificar permisos de carpeta
   ls -la ~/Desktop/
   
   # Probar diferente ubicación de guardado
   # Usar carpeta Documentos en lugar de Escritorio
   

2. Problemas de Espacio en Disco:

   # Verificar espacio disponible en disco
   df -h
   
   # Necesita al menos 2x tamaño de exportación libre
   

3. Problemas de Formato de Archivo:

   • CSV: Probar diferente delimitador (coma, punto y coma, tabulador)
   • CSV: Agregar calificadores de texto (comillas alrededor de campos)
   • JSON: Probar formatos "Legible" y "Compacto"

4. Optimización de Exportación Grande:

   • Exportar en fragmentos más pequeños
   • Usar CSV en lugar de JSON para conjuntos de datos grandes
   • Habilitar compresión en configuraciones de exportación

"Archivo No Encontrado" o Exportaciones Faltantes

1. Verificar Ubicación de Guardado Predeterminada:

   • Preferencias → Exportar → Ubicación de Guardado Predeterminada
   • Cambiar a carpeta de acceso frecuente

2. Buscar Archivos:

   # Buscar archivos CSV/JSON recientes
   find ~ -name "*.csv" -mtime -1
   find ~ -name "*.json" -mtime -1
   

3. Verificar Papelera:

   • Las exportaciones pueden haber sido eliminadas accidentalmente
   • Restaurar desde Papelera si se encuentran

Problemas de Interfaz y Visualización

Tema No Se Aplica Correctamente

Problemas con Modo Oscuro/Claro de macOS:

1. Verificar Configuración del Sistema:

   • Configuración del Sistema → Apariencia
   • Asegurar "Automático" o tema deseado seleccionado

2. Reiniciar HarborDB:

   • Salir completamente (⌘ + Q)
   • Reabrir para aplicar tema del sistema

3. Forzar Tema en HarborDB:

   • Preferencias → Apariencia → Tema
   • Elegir "Claro", "Oscuro" o "Sistema"

Características o Menús Faltantes

1. Actualizar HarborDB:

   • Buscar actualizaciones (HarborDB → Buscar Actualizaciones)
   • App Store → Pestaña Actualizaciones

2. Restablecer Diseño de Interfaz:

   • Ventana → Restablecer Diseño
   • Restaura disposición predeterminada de paneles

3. Verificar Disponibilidad de Características:

   • Algunas características requieren versiones específicas de PostgreSQL
   • Verificar compatibilidad en documentación de características

Problemas de Visualización de Texto

Problemas de Tamaño de Fuente/Legibilidad:

1. Ajustar Tamaño de Fuente del Editor:

   • Preferencias → Editor → Tamaño de Fuente
   • Aumentar para mejor legibilidad

2. Usar Zoom de macOS:

   • Configuración del Sistema → Accesibilidad → Zoom
   • Habilitar para magnificación temporal

3. Modo de Alto Contraste:

   • Configuración del Sistema → Accesibilidad → Pantalla
   • Aumentar contraste para mejor visibilidad

Problemas Específicos de macOS

Error "La aplicación está dañada"

Al abrir HarborDB:

# Eliminar atributo de cuarentena
sudo xattr -cr /Applications/HarborDB.app

# Reabrir HarborDB
open /Applications/HarborDB.app

Advertencias de Gatekeeper

Para descargas directas (no App Store):

1. Configuración del Sistema → Privacidad y Seguridad
2. Desplazar a sección "Seguridad"
3. Hacer clic en "Abrir de todos modos" junto a advertencia de HarborDB
4. Confirmar apertura

Problemas de Touch ID/Acceso a Keychain

Errores "HarborDB quiere usar su contraseña":

1. Restablecer Permisos de Keychain:

   • Abrir aplicación Acceso a Keychain
   • Buscar "HarborDB"
   • Eliminar entradas existentes
   • Volver a agregar conexión en HarborDB

2. Reparar Keychain:

   • Acceso a Keychain → Archivo → Reparar Keychain
   • Ejecutar reparación en keychain "Login"

Compatibilidad con Versiones de macOS

Mínimo: macOS 12.0 (Monterey) Recomendado: macOS 13.0 (Ventura) o posterior

Verificar Compatibilidad:

# Verificar versión de macOS
sw_vers

# Verificar arquitectura (Apple Silicon vs Intel)
uname -m

Problemas Específicos de Base de Datos

"La relación no existe"

Al consultar tablas:

1. Verificar Esquema:

   -- Listar todas las tablas en esquema actual
   \dt
   
   -- Listar tablas en todos los esquemas
   SELECT schemaname, tablename
   FROM pg_tables
   WHERE tablename LIKE '%su_tabla%';
   

2. Usar Nombres Calificados:

   -- En lugar de: SELECT * FROM usuarios;
   -- Usar calificación de esquema:
   SELECT * FROM public.usuarios;
   SELECT * FROM auth.usuarios;
   

3. Establecer Esquema Predeterminado:

   • Editar conexión en HarborDB
   • Establecer "Esquema Predeterminado" a esquema de uso común

Errores de Permiso en Objetos de Base de Datos

Permiso denegado para relación

1. Verificar Sus Permisos:

   -- Conectarse como superusuario o dueño de tabla
   SELECT grantee, privilege_type
   FROM information_schema.role_table_grants
   WHERE table_name = 'su_tabla';
   

2. Solicitar Permisos:

   -- Ejemplo: Otorgar permiso SELECT
   GRANT SELECT ON nombre_tabla TO su_nombre_usuario;
   

Manejo de Conjuntos de Datos Grandes

"Sin memoria" o extremadamente lento:

1. Usar Paginación del Lado del Servidor:

   -- En lugar de: SELECT * FROM tabla_grande;
   -- Usar:
   SELECT * FROM tabla_grande LIMIT 1000 OFFSET 0;
   -- Luego incrementar OFFSET para siguientes páginas
   

2. Habilitar Transmisión en HarborDB:

   • Preferencias → Rendimiento → Modo de Transmisión
   • Establecer umbral (ej., 10,000 filas)

3. Usar Vistas Materializadas para consultas complejas frecuentes

Problemas de Red y Conexiones Remotas

Conexiones Remotas Lentas

Consejos de Optimización:

1. Habilitar Compresión:

   • Configuración de conexión → Avanzado → Compresión
   • Reduce tamaño de transferencia de datos

2. Usar Túnel SSH:

   • Más seguro que conexión directa
   • Puede mejorar rendimiento en redes restringidas

3. Programar Consultas Pesadas:

   • Ejecutar durante horas de menor actividad
   • Usar característica de programador de consultas de HarborDB

Caídas Intermitentes de Conexión

1. Aumentar Configuraciones de Tiempo de Espera:

   • Configuración de conexión → Tiempo de Espera
   • Aumentar de 30 a 60 segundos

2. Habilitar Keep-Alive:

   • Configuración de conexión → Keep-Alive
   • Mantiene conexiones inactivas

3. Verificar Estabilidad de Red:

   # Probar estabilidad de red
   ping -c 100 su-dirección-servidor
   # Buscar pérdida de paquetes
   

Antes de Contactar al Soporte

Información para Recopilar

Si los problemas persisten después de la solución de problemas, recopile esta información:

1. Información del Sistema:

   • Versión de macOS (Menú Apple → Acerca de este Mac)
   • Versión de HarborDB (HarborDB → Acerca de HarborDB)
   • Versión de PostgreSQL (SELECT version();)

2. Detalles del Error:

   • Mensaje de error exacto (captura de pantalla si es posible)
   • Pasos para reproducir el problema
   • Cuándo comenzó el problema

3. Detalles de Configuración:

   • Configuración de conexión (sin contraseñas)
   • Consulta causando problemas (si aplica)
   • Configuración de exportación (si relacionado con exportación)

Herramientas de Diagnóstico en HarborDB

1. Generar Informe de Diagnóstico:

   • Ayuda → Crear Informe de Diagnóstico
   • Incluye registros, configuración, información del sistema

2. Ver Registros de Aplicación:

   • Ayuda → Mostrar Registros
   • Filtrar por mensajes de error y advertencia

3. Console.app para Registros del Sistema:

   • Abrir Console.app
   • Buscar "HarborDB"
   • Buscar informes de fallos

Autoverificación Rápida

Antes de contactar al soporte, verificar:

• [ ] macOS está actualizado
• [ ] HarborDB es la última versión
• [ ] Servidor PostgreSQL está ejecutándose
• [ ] Conexión de red es estable
• [ ] Hay suficiente espacio en disco disponible
• [ ] Usuario tiene permisos necesarios

Contactando al Soporte

Si ha intentado todos los pasos de solución de problemas y el problema persiste:

1. Correo de Soporte: support@harbordb.com

2. Incluir en su correo:

   • Informe de diagnóstico (desde menú Ayuda)
   • Capturas de pantalla de mensajes de error
   • Pasos para reproducir el problema
   • Qué pasos de solución de problemas ha intentado

3. Tiempo de Respuesta Esperado:

   • Respuesta inicial: Dentro de 24-48 horas
   • Horario comercial: Lunes-Viernes, 9AM-5PM EST
   • Problemas de emergencia: Marcar correo como "URGENTE"

Medidas Preventivas

Mantenimiento Regular

Semanal:

• Reiniciar HarborDB para limpiar memoria
• Limpiar archivos temporales de exportación
• Respaldar configuraciones importantes de conexión

Mensual:

• Actualizar HarborDB y PostgreSQL
• Revisar y optimizar consultas lentas
• Limpiar conexiones no utilizadas

Mejores Prácticas para Evitar Problemas

1. Gestión de Conexiones:

   • Usar nombres de conexión significativos
   • Probar conexiones regularmente
   • Eliminar conexiones no utilizadas

2. Desarrollo de Consultas:

   • Siempre usar LIMIT durante exploración
   • Probar con EXPLAIN antes de ejecutar consultas grandes
   • Guardar consultas complejas para reutilización

3. Mantenimiento del Sistema:

   • Mantener macOS actualizado
   • Respaldos regulares de Time Machine
   • Monitorear espacio en disco

Recursos Adicionales

• FAQ de HarborDB - Respuestas a preguntas comunes
• Guía de Introducción - Instalación y configuración
• Optimización de Rendimiento - Ajuste avanzado
• Guía de Seguridad de macOS - Mejores prácticas de seguridad

---

Solución de problemas es un proceso iterativo. Comience con las soluciones más simples y avance hacia las más complejas. Recuerde documentar lo que funciona para referencia futura.

Última actualización: {{current_date}}