Bem-vindo ao guia de solução de problemas do HarborDB. Este recurso abrangente ajuda você a identificar e resolver rapidamente os problemas mais comuns encontrados ao trabalhar com HarborDB e PostgreSQL. Seja você esteja enfrentando problemas de conexão, desempenho lento ou problemas de interface, encontrará soluções passo a passo aqui.

Como Usar Este Guia

Identifique seu problema nas categorias abaixo
Siga as etapas de solução de problemas em ordem
Tente as soluções até que o problema seja resolvido
Se ainda não resolvido, use a seção "Contatando o Suporte"

Referência Rápida: Problemas Comuns

| Problema | Causa Provável | Solução Rápida | | ---------------------------- | -------------------------------------- | ----------------------------------------- | | Não consigo conectar ao PostgreSQL | Servidor não em execução, firewall bloqueando | Inicie o PostgreSQL, verifique configurações do firewall | | Desempenho de consulta lento | Índices ausentes, grandes conjuntos de dados | Adicione índices, use LIMIT, otimize consultas | | Uso alto de memória | Muitas abas abertas, grandes conjuntos de resultados | Feche abas não utilizadas, habilite modo de streaming | | Falha na exportação | Problemas de permissão, disco cheio | Verifique permissões de arquivo, libere espaço em disco | | Interface parece lenta | Restrições de recursos do sistema | Feche outros aplicativos, reinicie o HarborDB |

Problemas de Conexão

"Não é possível conectar ao servidor PostgreSQL"

Sintomas:

Erros de timeout de conexão
Mensagens "Conexão recusada"
Carregamento infinito ao testar conexão

Solução de Problemas Passo a Passo:

Verifique o Status do Servidor PostgreSQL:
```
# No Terminal, verifique se o PostgreSQL está em execução
pg_isready -h localhost -p 5432
```
- Se não estiver em execução: brew services start postgresql (Homebrew) ou inicie via Preferências do Sistema
Verifique os Detalhes da Conexão:
- Nome do host: localhost para local, IP/nome de host correto para remoto
- Porta: Padrão é 5432, confirme sua porta PostgreSQL
- Nome do banco de dados: Deve existir antes de conectar
- Nome de usuário/senha: Sensível a maiúsculas/minúsculas, verifique credenciais
Verifique as Configurações do Firewall:
- Preferências do Sistema → Segurança e Privacidade → Firewall
- Certifique-se de que a porta PostgreSQL (5432) é permitida
- Tente desabilitar temporariamente o firewall para teste

Teste a Conectividade de Rede:

# Para servidores remotos
ping seu-endereço-servidor
telnet seu-endereço-servidor 5432

Soluções Comuns:

✅ Inicie o serviço PostgreSQL
✅ Corrija nome do host/endereço IP
✅ Abra a porta do firewall 5432
✅ Use credenciais corretas

"Falha na autenticação da senha"

Causas:

Nome de usuário ou senha incorretos
Incompatibilidade do método de autenticação PostgreSQL
Usuário não possui permissões de banco de dados

Soluções:

Redefina a Senha PostgreSQL:

-- Conecte-se como superusuário (via linha de comando)
ALTER USER nome_de_usuario WITH PASSWORD 'nova_senha';

Verifique o Método de Autenticação:
- Visualize o arquivo pg_hba.conf
- Métodos comuns: md5, scram-sha-256, trust
- Atualize o método se necessário, reinicie o PostgreSQL

Verifique as Permissões do Usuário:

-- Liste usuários e permissões
\du

-- Liste bancos de dados e acesso
\l

Erros de Conexão SSL/TLS

Ao conectar a servidores remotos:

Verifique os Requisitos SSL:
- O servidor pode exigir modo SSL específico
- Pode precisar importar certificado
Tente Diferentes Modos SSL no HarborDB:
- Comece com preferir
- Então tente exigir
- Finalmente verificar-completo (requer certificado)
Importe Certificados se usar verificar-completo:
- Obtenha certificado do administrador do servidor
- Importe para Acesso ao Keychain do macOS
- Conceda acesso do HarborDB ao certificado

Problemas de Desempenho

Execução Lenta de Consultas

Etapas de Diagnóstico:

Use EXPLAIN para Analisar:
- Clique no botão "Explain" (⚡) no HarborDB
- Procure por "Seq Scan" (varredura completa da tabela) - frequentemente lento
- Procure por "Index Scan" - geralmente mais rápido

Verifique Índices Ausentes:

-- Encontre colunas filtradas frequentemente sem í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
  );

Adicione Índices Apropriados:

-- Índice de coluna única
CREATE INDEX idx_tabela_coluna ON nome_da_tabela(nome_da_coluna);

-- Índice de múltiplas colunas para padrões de consulta comuns
CREATE INDEX idx_tabela_col1_col2 ON nome_da_tabela(col1, col2);

Correções Rápidas de Desempenho:

Adicione cláusula LIMIT a consultas exploratórias
Selecione apenas colunas necessárias (não SELECT *)
Use cláusulas WHERE com colunas indexadas
Evite funções em cláusulas WHERE que impeçam uso de índice

Uso Alto de Memória

Sintomas:

HarborDB usa RAM excessiva (verifique Monitor de Atividade)
Sistema fica lento
Erros "Memória insuficiente"

Soluções:

Reduza o Tamanho do Cache de Consultas:
- Preferências → Desempenho → Cache de Consultas
- Reduza de 256MB padrão para 128MB se limitado por memória
Habilite Modo de Streaming:
- Preferências → Desempenho → Resultados em Streaming
- Habilite para resultados > 10.000 linhas
- Reduz uso de memória para grandes conjuntos de dados
Gerencie Abas Abertas:
- Feche abas de consulta não utilizadas
- HarborDB mantém conjuntos de resultados na memória por aba
- Trabalho regular: máximo de 5-10 abas
Reinicie o HarborDB:
- Saia e reinicie diariamente durante uso intenso
- Limpa uso de memória acumulado

Aplicativo Parece Lento

Correções Rápidas:

Feche Outros Aplicativos:
- Especialmente aplicativos intensivos em recursos (Chrome com muitas abas, Docker, etc.)
- Verifique pressão de memória no Monitor de Atividade
Reduza Animações da Interface:
- Preferências → Aparência → Desabilite animações
- Experiência mais suave em hardware mais antigo
Simplifique a Interface:
- Recolha seções da barra lateral não em uso
- Use tema de cores mais simples
- Desabilite realce de sintaxe para consultas muito grandes

Problemas de Exportação e Arquivos

Exportação Falha ou Cria Arquivos Vazios

Causas e Soluções Comuns:

Problemas de Permissão:

# Verifique permissões de pasta
ls -la ~/Desktop/

# Tente local de salvamento diferente
# Use pasta Documentos em vez de Desktop

Problemas de Espaço em Disco:

# Verifique espaço em disco disponível
df -h

# Precisa de pelo menos 2x o tamanho da exportação livre

Problemas de Formato de Arquivo:
- CSV: Tente delimitador diferente (vírgula, ponto e vírgula, tab)
- CSV: Adicione qualificadores de texto (aspas ao redor dos campos)
- JSON: Tente ambos os formatos "Pretty" e "Compact"
Otimização de Exportação Grande:
- Exporte em pedaços menores
- Use CSV em vez de JSON para grandes conjuntos de dados
- Habilite compressão nas configurações de exportação

"Arquivo Não Encontrado" ou Exportações Ausentes

Verifique Local de Salvamento Padrão:
- Preferências → Exportação → Local de Salvamento Padrão
- Mude para pasta acessada frequentemente

Pesquise por Arquivos:

# Pesquise por arquivos CSV/JSON recentes
find ~ -name "*.csv" -mtime -1
find ~ -name "*.json" -mtime -1

Verifique Lixeira:
- Exportações podem ter sido acidentalmente excluídas
- Restaure da Lixeira se encontrado

Problemas de Interface e Exibição

Tema Não Aplicado Corretamente

Problemas de Modo Escuro/Claro do macOS:

Verifique Configurações do Sistema:
- Configurações do Sistema → Aparência
- Certifique-se de que "Automático" ou tema desejado está selecionado
Reinicie o HarborDB:
- Saia completamente (⌘ + Q)
- Reabra para aplicar tema do sistema
Force Tema no HarborDB:
- Preferências → Aparência → Tema
- Escolha "Claro", "Escuro" ou "Sistema"

Recursos ou Menus Ausentes

Atualize o HarborDB:
- Verifique atualizações (HarborDB → Verificar Atualizações)
- App Store → aba Atualizações
Redefina Layout da Interface:
- Janela → Redefinir Layout
- Restaura arranjo padrão de painéis
Verifique Disponibilidade de Recurso:
- Alguns recursos requerem versões específicas do PostgreSQL
- Verifique compatibilidade na documentação do recurso

Problemas de Exibição de Texto

Problemas de Tamanho de Fonte/Legibilidade:

Ajuste Tamanho da Fonte do Editor:
- Preferências → Editor → Tamanho da Fonte
- Aumente para melhor legibilidade
Use Zoom do macOS:
- Configurações do Sistema → Acessibilidade → Zoom
- Habilite para ampliação temporária
Modo de Alto Contraste:
- Configurações do Sistema → Acessibilidade → Exibição
- Aumente contraste para melhor visibilidade

Problemas Específicos do macOS

Erro "Aplicativo Está Danificado"

Ao abrir o HarborDB:

# Remova atributo de quarentena
sudo xattr -cr /Applications/HarborDB.app

# Reabra o HarborDB
open /Applications/HarborDB.app

Avisos do Gatekeeper

Para downloads diretos (não App Store):

Configurações do Sistema → Privacidade e Segurança
Role até a seção "Segurança"
Clique em "Abrir Mesmo Assim" ao lado do aviso do HarborDB
Confirme a abertura

Problemas de Acesso ao Touch ID/Keychain

Erros "HarborDB quer usar sua senha":

Redefina Permissões do Keychain:
- Abra o aplicativo Acesso ao Keychain
- Pesquise por "HarborDB"
- Exclua entradas existentes
- Adicione novamente conexão no HarborDB
Repare o Keychain:
- Acesso ao Keychain → Arquivo → Primeiros Socorros do Keychain
- Execute reparo no keychain "Login"

Compatibilidade com Versões do macOS

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

Verifique Compatibilidade:

# Verifique versão do macOS
sw_vers

# Verifique arquitetura (Apple Silicon vs Intel)
uname -m

Problemas Específicos do Banco de Dados

"Relação não existe"

Ao consultar tabelas:

Verifique Schema:

-- Liste todas as tabelas no schema atual
\dt

-- Liste tabelas em todos os schemas
SELECT schemaname, tablename
FROM pg_tables
WHERE tablename LIKE '%sua_tabela%';

Use Nomes Qualificados:

-- Em vez de: SELECT * FROM usuarios;
-- Use qualificação de schema:
SELECT * FROM public.usuarios;
SELECT * FROM auth.usuarios;

Defina Schema Padrão:
- Edite conexão no HarborDB
- Defina "Schema Padrão" para schema comumente usado

Erros de Permissão em Objetos do Banco de Dados

Permissão negada para relação

Verifique Suas Permissões:

-- Conecte-se como superusuário ou proprietário da tabela
SELECT grantee, privilege_type
FROM information_schema.role_table_grants
WHERE table_name = 'sua_tabela';

Solicite Permissões:

-- Exemplo: Conceder permissão SELECT
GRANT SELECT ON nome_da_tabela TO seu_nome_de_usuario;

Manipulação de Grandes Conjuntos de Dados

"Memória insuficiente" ou extremamente lento:

Use Paginação no Lado do Servidor:

-- Em vez de: SELECT * FROM tabela_enorme;
-- Use:
SELECT * FROM tabela_enorme LIMIT 1000 OFFSET 0;
-- Então incremente OFFSET para próximas páginas

Habilite Streaming no HarborDB:
- Preferências → Desempenho → Modo de Streaming
- Defina limite (ex.: 10.000 linhas)
Use Visualizações Materializadas para consultas complexas frequentes

Problemas de Rede e Conexão Remota

Conexões Remotas Lentas

Dicas de Otimização:

Habilite Compressão:
- Configurações de conexão → Avançado → Compressão
- Reduz tamanho da transferência de dados
Use Tunelamento SSH:
- Mais seguro que conexão direta
- Pode melhorar desempenho em redes restritas
Agende Consultas Pesadas:
- Execute durante horas de baixa demanda
- Use recurso de agendador de consultas do HarborDB

Quedas Intermitentes de Conexão

Aumente Configurações de Timeout:
- Configurações de conexão → Timeout
- Aumente de 30 para 60 segundos
Habilite Keep-Alive:
- Configurações de conexão → Keep-Alive
- Mantém conexões ociosas

Verifique Estabilidade da Rede:

# Teste estabilidade da rede
ping -c 100 seu-endereço-servidor
# Procure por perda de pacotes

Antes de Contatar o Suporte

Informações para Coletar

Se os problemas persistirem após solução de problemas, colete estas informações:

Informações do Sistema:
- Versão do macOS (Menu Apple → Sobre este Mac)
- Versão do HarborDB (HarborDB → Sobre HarborDB)
- Versão do PostgreSQL (SELECT version();)
Detalhes do Erro:
- Mensagem de erro exata (captura de tela se possível)
- Passos para reproduzir o problema
- Quando o problema começou
Detalhes de Configuração:
- Configurações de conexão (sem senhas)
- Consulta causando problemas (se aplicável)
- Configurações de exportação (se relacionado a exportação)

Ferramentas de Diagnóstico no HarborDB

Gere Relatório de Diagnóstico:
- Ajuda → Criar Relatório de Diagnóstico
- Inclui logs, configuração, informações do sistema
Visualize Logs do Aplicativo:
- Ajuda → Mostrar Logs
- Filtre por mensagens de erro e aviso
Console.app para Logs do Sistema:
- Abra Console.app
- Pesquise por "HarborDB"
- Procure por relatórios de falha

Verificação Rápida

Antes de contatar o suporte, verifique:

[ ] macOS está atualizado
[ ] HarborDB é a versão mais recente
[ ] Servidor PostgreSQL está em execução
[ ] Conexão de rede está estável
[ ] Espaço em disco suficiente disponível
[ ] Usuário tem permissões necessárias

Contatando o Suporte

Se você tentou todas as etapas de solução de problemas e o problema persiste:

Suporte por Email: suporte@harbordb.com
Inclua em seu email:
- Relatório de diagnóstico (do menu Ajuda)
- Capturas de tela das mensagens de erro
- Passos para reproduzir o problema
- Quais etapas de solução de problemas você tentou
Tempo de Resposta Esperado:
- Resposta inicial: Dentro de 24-48 horas
- Horário comercial: Segunda a Sexta, 9h-17h EST
- Problemas de emergência: Marque email como "URGENTE"

Medidas Preventivas

Manutenção Regular

Semanalmente:

Reinicie o HarborDB para limpar memória
Limpe arquivos de exportação temporários
Faça backup de configurações importantes de conexão

Mensalmente:

Atualize HarborDB e PostgreSQL
Revise e otimize consultas lentas
Limpe conexões não utilizadas

Melhores Práticas para Evitar Problemas

Gerenciamento de Conexão:
- Use nomes de conexão significativos
- Teste conexões regularmente
- Remova conexões não utilizadas
Desenvolvimento de Consultas:
- Sempre use LIMIT durante exploração
- Teste com EXPLAIN antes de executar consultas grandes
- Salve consultas complexas para reuso
Manutenção do Sistema:
- Mantenha o macOS atualizado
- Backups regulares do Time Machine
- Monitore espaço em disco

Recursos Adicionais

FAQ do HarborDB - Respostas a perguntas comuns
Guia de Introdução - Instalação e configuração
Otimização de Desempenho - Ajustes avançados
Guia de Segurança do macOS - Melhores práticas de segurança

Problemas Comuns e Solução de Problemas