¡Bienvenido a HarborDB! Esta guía te guiará a través del proceso de crear tu primera conexión PostgreSQL. Ya sea que te conectes a una base de datos local en tu Mac o a un servidor remoto, HarborDB hace que el proceso sea simple y seguro.

Prerrequisitos

Antes de comenzar, asegúrate de tener:

HarborDB instalado (consulta la Guía de instalación)
Servidor PostgreSQL en ejecución y accesible
Detalles de conexión listos:
- Nombre de host o dirección IP
- Número de puerto (predeterminado: 5432)
- Nombre de la base de datos
- Nombre de usuario y contraseña
- Opcional: certificado SSL si es requerido

Paso 1: Inicia HarborDB y accede a las conexiones

Abre HarborDB desde tu carpeta Aplicaciones o Launchpad
Localiza la barra lateral de Conexiones en el lado izquierdo de la ventana
Haz clic en el botón "+" o ve a Archivo → Agregar Conexión

Paso 2: Completa los detalles de la conexión

El diálogo de conexión tiene varios campos para completar:

Información Básica

Nombre: Un nombre amigable para esta conexión (ej.: "Desarrollo Local", "Servidor de Producción")
Host: La dirección del servidor PostgreSQL
- Base de datos local: localhost o 127.0.0.1
- Servidor remoto: Dirección IP o nombre de host (ej.: db.example.com)
Puerto: Puerto PostgreSQL (predeterminado: 5432)
Base de datos: La base de datos específica a la que conectarse
Nombre de usuario: Tu nombre de usuario PostgreSQL
Contraseña: Tu contraseña PostgreSQL

Opciones Avanzadas (Opcional)

Schema: Schema preferido (predeterminado: public)
Modo SSL: Elige según la configuración de tu servidor:
- preferir: Usar SSL si está disponible
- exigir: Requerir conexión SSL
- verificar-completo: Requerir SSL con validación de certificado
Tiempo de espera: Tiempo de espera de conexión en segundos
Nombre de la aplicación: Identificador personalizado para esta conexión

Paso 3: Prueba tu conexión

Antes de guardar, siempre prueba tu conexión:

Haz clic en "Probar Conexión" en el diálogo
Espera la confirmación - Deberías ver "Conexión exitosa"
Revisa cualquier advertencia sobre SSL u otras configuraciones

Resultados comunes de prueba

✅ Éxito: Estás listo para guardar y conectar
❌ Fallo: Revisa el mensaje de error para pistas:
- "Conexión rechazada": Servidor no en ejecución o firewall bloqueando
- "Autenticación fallida": Nombre de usuario/contraseña incorrectos
- "La base de datos no existe": Nombre de base de datos incorrecto

Paso 4: Guarda y protege tu conexión

Opciones de almacenamiento de contraseña

HarborDB ofrece almacenamiento seguro de contraseñas:

Guardar en Keychain (Recomendado): Contraseña encriptada en el Keychain de macOS
Guardar en conexión: Contraseña almacenada con la configuración de conexión (menos seguro)
Preguntar cada vez: Solicitar contraseña en cada conexión

Eligiendo la opción correcta

| Método de Almacenamiento | Seguridad | Conveniencia | Mejor para | | ------------------------ | ---------- | ------------ | -------------------------------- | | Keychain de macOS | 🔒 Alta | ⚡ Alta | Uso diario, computadoras confiables | | Archivo de conexión | 🔒 Media | ⚡ Alta | Configuración rápida, pruebas | | Preguntar cada vez | 🔒 Máxima | ⚡ Baja | Computadoras compartidas, alta seguridad |

Guardando tu conexión

Elige el método de almacenamiento de contraseña
Haz clic en "Guardar" para almacenar la conexión
Encuentra tu conexión en la barra lateral de Conexiones
Haz doble clic para conectar

Paso 5: Conecta y explora

Una vez conectado, puedes:

Navegar por tu base de datos

Expande la conexión para ver bases de datos
Explora schemas y tablas en la barra lateral
Haz clic derecho en tablas para acciones rápidas:
- Ver estructura de la tabla
- Vista previa de las primeras 100 filas
- Generar consulta SELECT

Acciones de inicio rápido

Abre el Editor de Consultas: Haz clic en el icono SQL o presiona ⌘ + N
Ejecuta una consulta de prueba:
```
SELECT version();
```
Explora la interfaz: Familiarízate con pestañas, paneles y herramientas

Gestión de conexiones

Organizando múltiples conexiones

A medida que agregas más conexiones, mantenlas organizadas:

Favoritas: Marca conexiones usadas frecuentemente para acceso rápido
Grupos: Organiza por proyecto, entorno o equipo
Codificación por colores: Usa etiquetas o convenciones de nomenclatura

Editando conexiones existentes

Haz clic derecho en la conexión en la barra lateral
Selecciona "Editar Conexión"
Actualiza cualquier campo según sea necesario
Prueba y guarda los cambios

Duplicando conexiones

Ahorra tiempo duplicando conexiones similares:

Haz clic derecho en la conexión fuente
Selecciona "Duplicar"
Modifica solo los campos cambiados
Guarda como nueva conexión

Mejores prácticas de seguridad

Seguridad de contraseñas

Nunca compartas contraseñas del Keychain
Usa contraseñas fuertes para usuarios PostgreSQL
Rota contraseñas periódicamente
Evita reutilizar contraseñas en diferentes servidores

Seguridad de conexión

Usa SSL para conexiones remotas
Limita permisos de base de datos a operaciones necesarias
Usa conexiones de solo lectura para informes
Audita regularmente los registros de conexión

Seguridad de red

Configuración de firewall: Permite solo IPs confiables
Acceso VPN para bases de datos remotas
Túnel SSH para capas adicionales de seguridad

Escenarios comunes de conexión

PostgreSQL local (Instalado via Homebrew)

Nombre: PostgreSQL Local
Host: localhost
Puerto: 5432
Base de datos: postgres
Nombre de usuario: tu_usuario
Contraseña: [Keychain]

Contenedor Docker PostgreSQL

Nombre: Docker Dev DB
Host: localhost
Puerto: 5432  # O puerto personalizado si mapeado diferente
Base de datos: app_database
Nombre de usuario: postgres
Contraseña: postgres_password

Amazon RDS PostgreSQL

Nombre: AWS Producción
Host: tu-instancia-db.region.rds.amazonaws.com
Puerto: 5432
Base de datos: production_db
Nombre de usuario: app_user
Modo SSL: verificar-completo

Google Cloud SQL

Nombre: GCP Cloud SQL
Host: /cloudsql/project:region:instance
Puerto: 5432
Base de datos: cloud_db
Modo SSL: exigir

Solución de problemas de conexión

"No se puede conectar al servidor"

Verifica que PostgreSQL esté en ejecución:

# En Terminal
pg_isready -h localhost -p 5432

Verifica configuración del firewall:
- Firewall de macOS (Preferencias del Sistema → Seguridad y Privacidad)
- Reglas del firewall de red

Prueba conectividad de red:

# En Terminal
ping tu-direccion-servidor
telnet tu-direccion-servidor 5432

"Fallo en la autenticación de contraseña"

Verifica método de autenticación de PostgreSQL:
- Visualiza el archivo pg_hba.conf
- Asegúrate de la autenticación md5 o scram-sha-256

Reinicia la contraseña si es necesario:

ALTER USER nombre_usuario WITH PASSWORD 'nueva_contraseña';

Verifica que el usuario tenga acceso a la base de datos:

-- Conéctate como superusuario
\du  -- Lista usuarios
\l   -- Lista bases de datos

Errores de conexión SSL/TLS

Verifica requisitos SSL:
- El servidor puede requerir modo SSL específico
- Puede necesitar importar certificado
Ajusta modo SSL en la configuración de conexión
Importa certificado si usas modo verificar-completo

Consejos de rendimiento

Agrupación de conexiones

Mantén conexiones abiertas para uso frecuente
Cierra conexiones no utilizadas para liberar recursos
Usa agrupación de conexiones para aplicaciones

Optimización de red

Conexiones locales: Usa localhost para mejor rendimiento
Conexiones remotas: Asegura ancho de banda suficiente
Compresión: Habilita si trabajas con grandes conjuntos de resultados

Próximos pasos

Ahora que estás conectado:

Explora Fundamentos de Consultas - Aprende a escribir y ejecutar consultas SQL
Navegación de Bases de Datos - Explora schemas, tablas y relaciones
Exportación de Datos - Guarda resultados en CSV o JSON

Obteniendo ayuda

Si todavía tienes problemas:

Consulta nuestra Guía de Soporte para más solución de problemas
Visita el FAQ para preguntas comunes
Contacta con Soporte para asistencia personalizada

Creando tu primera conexión