Configuração

5 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
# Optional — enables JWT sessions (POST /db//token):
# JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Variáveis obrigatórias: DB_HOST, DB_PORT, DB_USER.

JWT_SECRET é opcional. Defina-o (mínimo de 32 bytes; gere com openssl rand -hex 32) para habilitar sessões JWT via POST /{prefix}/{database}/token e JWTs emitidos externamente. Sem ele, o suporte a JWT fica desativado e os clientes se autenticam com credenciais HTTP Basic (usuário e senha do banco de dados) ou tokens de API de longa duração.

Lista de Verificação Rápida

  • Se o JWT estiver habilitado, 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, /file, /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 & login)
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. Se não for definida, o suporte a JWT fica desativado: o endpoint /token fica indisponível e os clientes se autenticam apenas com credenciais HTTP Basic ou tokens de API.
JWT_EXPIRY_HOURS○Validade da sessão em horas (deve ser maior que 0). 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 autenticação por IP do cliente e nome de usuário por janela. Aplica-se a todos os métodos de login: cada requisição a /token conta e, para credenciais HTTP Basic (em todos os endpoints), contam as tentativas falhas. Padrão: 5. Use 0 para desativar.
LOGIN_RATE_LIMIT_PER_IP○Máximo de tentativas de autenticação por IP do cliente entre todos os nomes de usuário, para que alternar nomes não contorne o limite. Também conta tentativas Bearer falhas (JWT ou token de API inválido). 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.
FILE_MAX_BYTES○Tamanho total máximo descompactado de uma resposta /file em bytes. Padrão: 67108864 (64 MiB).
FILE_MAX_ENTRIES○Número máximo de arquivos em uma resposta /file. Padrão: 1000.
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

Documentação relacionada

← Instalação JSON-RPC →