Bem-vindo ao HarborDB! Este guia irá orientá-lo através da criação da sua primeira conexão PostgreSQL. Seja para conectar-se a um banco de dados local no seu Mac ou a um servidor remoto, o HarborDB torna o processo simples e seguro.

Pré-requisitos

Antes de começar, certifique-se de ter:

HarborDB instalado (veja o Guia de Instalação)
Servidor PostgreSQL em execução e acessível
Detalhes da conexão prontos:
- Nome do host ou endereço IP
- Número da porta (padrão: 5432)
- Nome do banco de dados
- Nome de usuário e senha
- Opcional: Certificado SSL se necessário

Passo 1: Inicie o HarborDB e Acesse Conexões

Abra o HarborDB da sua pasta Aplicativos ou Launchpad
Localize a barra lateral de Conexões no lado esquerdo da janela
Clique no botão "+" ou vá para Arquivo → Adicionar Conexão

Passo 2: Preencha os Detalhes da Conexão

O diálogo de conexão tem vários campos para completar:

Informações Básicas

Nome: Um nome amigável para esta conexão (ex: "Desenvolvimento Local", "Servidor de Produção")
Host: O endereço do servidor PostgreSQL
- Banco de dados local: localhost ou 127.0.0.1
- Servidor remoto: Endereço IP ou nome do host (ex: db.example.com)
Porta: Porta PostgreSQL (padrão: 5432)
Banco de dados: O banco de dados específico para conectar
Nome de usuário: Seu nome de usuário PostgreSQL
Senha: Sua senha PostgreSQL

Opções Avançadas (Opcional)

Schema: Schema preferido (padrão: public)
Modo SSL: Escolha com base na configuração do seu servidor:
- prefer: Use SSL se disponível
- require: Exija conexão SSL
- verify-full: Exija SSL com validação de certificado
Timeout: Tempo limite de conexão em segundos
Nome do Aplicativo: Identificador personalizado para esta conexão

Passo 3: Teste Sua Conexão

Antes de salvar, sempre teste sua conexão:

Clique em "Testar Conexão" no diálogo
Aguarde a confirmação - Você deve ver "Conexão bem-sucedida"
Revise quaisquer avisos sobre SSL ou outras configurações

Resultados Comuns de Teste

✅ Sucesso: Você está pronto para salvar e conectar
❌ Falha: Verifique a mensagem de erro para pistas:
- "Conexão recusada": Servidor não está em execução ou firewall bloqueando
- "Falha na autenticação": Nome de usuário/senha incorretos
- "Banco de dados não existe": Nome do banco de dados incorreto

Passo 4: Salve e Proteja Sua Conexão

Opções de Armazenamento de Senha

O HarborDB oferece armazenamento seguro de senhas:

Salvar no Keychain (Recomendado): Senha criptografada no Keychain do macOS
Salvar na conexão: Senha armazenada com as configurações de conexão (menos seguro)
Perguntar cada vez: Solicitar senha em toda conexão

Escolhendo a Opção Certa

| Método de Armazenamento | Segurança | Conveniência | Melhor Para | | ----------------------- | ----------- | ------------ | ----------------------------------- | | Keychain do macOS | 🔒 Alta | ⚡ Alta | Uso diário, computadores confiáveis | | Arquivo de conexão | 🔒 Média | ⚡ Alta | Configuração rápida, testes | | Perguntar cada vez | 🔒 Mais alta | ⚡ Baixa | Computadores compartilhados, alta segurança |

Salvando Sua Conexão

Escolha o método de armazenamento de senha
Clique em "Salvar" para armazenar a conexão
Encontre sua conexão na barra lateral de Conexões
Clique duas vezes para conectar

Passo 5: Conecte-se e Explore

Uma vez conectado, você pode:

Navegue pelo Seu Banco de Dados

Expanda a conexão para ver bancos de dados
Navegue por schemas e tabelas na barra lateral
Clique com o botão direito em tabelas para ações rápidas:
- Ver estrutura da tabela
- Visualizar primeiras 100 linhas
- Gerar consulta SELECT

Ações de Início Rápido

Abra o Editor de Consultas: Clique no ícone SQL ou pressione ⌘ + N
Execute uma consulta de teste:
```
SELECT version();
```
Explore a interface: Familiarize-se com abas, painéis e ferramentas

Gerenciamento de Conexões

Organizando Múltiplas Conexões

Conforme você adiciona mais conexões, mantenha-as organizadas:

Favoritas: Marque conexões usadas frequentemente para acesso rápido
Grupos: Organize por projeto, ambiente ou equipe
Codificação por cores: Use tags ou convenções de nomenclatura

Editando Conexões Existentes

Clique com o botão direito na conexão na barra lateral
Selecione "Editar Conexão"
Atualize quaisquer campos conforme necessário
Teste e salve as alterações

Duplicando Conexões

Economize tempo duplicando conexões semelhantes:

Clique com o botão direito na conexão de origem
Selecione "Duplicar"
Modifique apenas os campos alterados
Salve como nova conexão

Melhores Práticas de Segurança

Segurança de Senha

Nunca compartilhe senhas do Keychain
Use senhas fortes para usuários PostgreSQL
Rotacione senhas periodicamente
Evite reutilizar senhas em diferentes servidores

Segurança da Conexão

Use SSL para conexões remotas
Limite permissões do banco de dados para operações necessárias
Use conexões somente leitura para relatórios
Audite regularmente logs de conexão

Segurança de Rede

Configuração de firewall: Permita apenas IPs confiáveis
Acesso VPN para bancos de dados remotos
Túnel SSH para camadas de segurança adicionais

Cenários Comuns de Conexão

PostgreSQL Local (Instalado via Homebrew)

Nome: PostgreSQL Local
Host: localhost
Porta: 5432
Banco de dados: postgres
Nome de usuário: seu_usuario
Senha: [Keychain]

Container Docker PostgreSQL

Nome: Docker Dev DB
Host: localhost
Porta: 5432  # Ou porta personalizada se mapeada diferentemente
Banco de dados: app_database
Nome de usuário: postgres
Senha: postgres_password

Amazon RDS PostgreSQL

Nome: AWS Produção
Host: your-db-instance.region.rds.amazonaws.com
Porta: 5432
Banco de dados: production_db
Nome de usuário: app_user
Modo SSL: verify-full

Google Cloud SQL

Nome: GCP Cloud SQL
Host: /cloudsql/project:region:instance
Porta: 5432
Banco de dados: cloud_db
Modo SSL: require

Solução de Problemas de Conexão

"Não é Possível Conectar ao Servidor"

Verifique se o PostgreSQL está em execução:

# No Terminal
pg_isready -h localhost -p 5432

Verifique configurações de firewall:
- Firewall do macOS (Preferências do Sistema → Segurança e Privacidade)
- Regras de firewall de rede

Teste conect ividade de rede:

# No Terminal
ping your-server-address
telnet your-server-address 5432

"Falha na Autenticação da Senha"

Verifique método de autenticação PostgreSQL:
- Visualize arquivo pg_hba.conf
- Certifique-se de autenticação md5 ou scram-sha-256

Redefina a senha se necessário:

ALTER USER usuario WITH PASSWORD 'nova_senha';

Verifique se o usuário tem acesso ao banco de dados:

-- Conecte-se como superusuário
\du  -- Listar usuários
\l   -- Listar bancos de dados

Erros de Conexão SSL/TLS

Verifique requisitos SSL:
- Servidor pode exigir modo SSL específico
- Certificado pode precisar ser importado
Ajuste o modo SSL nas configurações de conexão
Importe certificado se usar modo verify-full

Dicas de Desempenho

Pool de Conexões

Mantenha conexões abertas para uso frequente
Feche conexões não utilizadas para liberar recursos
Use pool de conexões para aplicações

Otimização de Rede

Conexões locais: Use localhost para melhor desempenho
Conexões remotas: Garanta largura de banda suficiente
Compressão: Ative se lidar com grandes conjuntos de resultados

Próximos Passos

Agora que você está conectado:

Explore Noções Básicas de Consultas - Aprenda a escrever e executar consultas SQL
Navegação no Banco de Dados - Explore schemas, tabelas e relacionamentos
Exportando Dados - Salve resultados em CSV ou JSON

Obtendo Ajuda

Se ainda estiver com problemas:

Verifique nosso Guia de Suporte para mais solução de problemas
Visite o FAQ para perguntas comuns
Entre em Contato com o Suporte para assistência personalizada

Criando Sua Primeira Conexão