Configuração

4 min de leitura

Início rápido

  1. Instale o PgArachne
  2. Configure o ambiente
  3. Configure segurança e auth
  4. Faça deploy atrás de proxy HTTPS

Configuração

O PgArachne carrega a configuração a partir de variáveis de ambiente ou de um arquivo.

Nota: schema.sql tenta criar o papel pgarachne_admin e concedê-lo a pgarachne. Sem privilégios de superusuário, a criação é ignorada. Crie o papel e o grant manualmente se necessário.
O usuário proxy (DB_USER) deve ser membro de pgarachne e pgarachne_admin para validar e criar tokens de API.
Nota de Segurança: O PgArachne não lida com senhas do banco de dados no arquivo de configuração. Ele depende do mecanismo padrão de arquivo .pgpass do PostgreSQL (ou da variável de sistema PGPASSWORD) para autenticação.
Dica: Se o PgArachne estiver atrás de um reverse proxy, defina TRUSTED_PROXIES para resolver corretamente o IP do cliente e evitar spoofing do rate limit.
Ordem de Busca: Se nenhum arquivo de configuração for especificado via CLI, ele busca em:
  1. Diretório atual: ./pgarachne.env (Todos os SOs)
  2. Configuração do usuário:
    • Linux/macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Configuração do sistema: /etc/pgarachne/pgarachne.env (Somente Linux/macOS)

Exemplo de Configuração Mínima

É tudo o que você precisa para começar:

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Variáveis obrigatórias: DB_HOST, DB_PORT, DB_USER, JWT_SECRET (mínimo de 32 bytes; gere com openssl rand -hex 32).

Lista de Verificação Rápida

  • JWT_SECRET é longo, aleatório e não reutilizado entre ambientes.
  • DB_USER só pode alternar para os papéis esperados (verifique os grants de membership).
  • TRUSTED_PROXIES está definido ao executar atrás de um reverse proxy.
  • LOGIN_RATE_LIMIT está habilitado para implantações expostas à internet.
  • METRICS_LISTEN_ADDR é privado (por exemplo 127.0.0.1:9090).

Referência de Configuração

VariávelObrigatórioDescrição
Conexão com Banco de Dados
DB_HOST✓Endereço do servidor PostgreSQL (ex: localhost).
DB_PORT✓Porta do banco de dados.
DB_USER✓O usuário do banco de dados com o qual o PgArachne se conecta.
DB_SSLMODE○Modo SSL do PostgreSQL. Padrão: require. Defina disable explicitamente apenas para desenvolvimento local contra um PostgreSQL sem TLS.
DB_SSLROOTCERT○Caminho do certificado raiz da CA (PEM).
DB_SSLCERT○Caminho do certificado do cliente (PEM).
DB_SSLKEY○Caminho da chave privada do cliente (PEM).
Servidor HTTP
HTTP_PORT○Porta para escutar. Padrão: 8080.
API_PREFIX○Primeiro segmento do caminho URL para todos os endpoints do banco de dados (/jsonrpc, /sse, /mcp). Padrão: db, gerando rotas como /db/:banco_de_dados/jsonrpc. Apenas letras, dígitos, hífens e underscores são permitidos.
PID_FILE○Caminho do arquivo PID do daemon usado por -start/-stop. Padrão: cache do usuário (fallback: diretório temporário).
ALLOWED_ORIGINS○Configurações de CORS. Lista separada por vírgulas de domínios permitidos (ex: https://meuapp.com). Padrão: não definido — as requisições cross-origin do navegador ficam desabilitadas. Defina * explicitamente para permitir qualquer origem.
STATIC_FILES_PATH○Caminho absoluto para servir arquivos estáticos (Explorer/Frontend).
Segurança (JWT)
JWT_SECRET✓Uma string longa e aleatória usada para assinar tokens de sessão. Mínimo de 32 bytes; gere com openssl rand -hex 32.
JWT_EXPIRY_HOURS○Validade da sessão em horas. Padrão: 8.
JWT_ISSUER○Se definido, é escrito no claim iss ao emitir e deve corresponder exatamente na validação. Deixe vazio para não verificar o issuer.
JWT_AUDIENCE○Se definido, é escrito no claim aud ao emitir e deve corresponder na validação. Deixe vazio para não verificar o audience.
JWT_LEEWAY○Tolerância de relógio para exp/nbf/iat (ex. 30s). Padrão: 30s.
LOGIN_RATE_LIMIT○Máximo de tentativas de login por janela. Padrão: 5. Use 0 para desativar.
LOGIN_RATE_LIMIT_PER_IP○Máximo de tentativas de login por IP do cliente entre todos os nomes de usuário, para que alternar nomes não contorne o limite. Padrão: 5× LOGIN_RATE_LIMIT. Use 0 para desativar.
LOGIN_RATE_WINDOW○Duração da janela do rate limit. Padrão: 1m.
O rate limit de login é por instância (em memória). Em várias instâncias, use um limitador compartilhado.
TRUSTED_PROXIES○Proxies confiáveis (IP/CIDR) para X-Forwarded-For. Separados por vírgula. Se vazio, os headers encaminhados são ignorados e o IP do cliente é obtido da conexão direta.
MAX_REQUEST_BYTES○Tamanho máximo do body em bytes. Padrão: 2097152.
MCP_SQL_ERROR_DETAIL○Incluir a mensagem de erro bruta do PostgreSQL nos erros das ferramentas MCP. Erros detalhados ajudam agentes LLM a se autocorrigirem, mas podem expor detalhes do esquema (nomes de tabelas e restrições) a chamadores autenticados. Padrão: false.
DIRECT_POOL_LIMIT○Número máximo de pools de conexão distintos para credenciais Basic Auth. Padrão: 1000.
METRICS_ENABLED○Habilita endpoint dedicado de métricas. Padrão: true.
METRICS_LISTEN_ADDR○Endereço do listener de métricas (host:port). Padrão: 127.0.0.1:9090.
SSE_MAX_CHANNELS○Máximo de canais por conexão SSE. Padrão: 8.
SSE_MAX_CLIENTS○Máximo de clientes SSE simultâneos por banco de dados. Padrão: 1000.
SSE_CLIENT_BUFFER○Buffer SSE por cliente (número de mensagens). Padrão: 64.
SSE_SEND_TIMEOUT○Tempo máximo de espera ao enviar para cliente lento. Padrão: 2s.
SSE_HEARTBEAT○Intervalo de heartbeat para SSE. Padrão: 20s.
SSE_IDLE_TIMEOUT○Timeout de inatividade sem notificações. Padrão: 90s.
Logging
LOG_LEVEL○Verbosidade: DEBUG, INFO, WARN, ERROR. Padrão: INFO.
LOG_OUTPUT○Onde gravar logs: stdout ou caminho do arquivo.

Obrigatório – Opcional

Comportamento de segurança: requisições sem um header Authorization válido são rejeitadas antes de abrir conexão com o banco.

Inicie o servidor:

./pgarachne -config .env

Veja também

Documentação relacionada

← Instalação Exemplo Hello World →