PgArachne

Sobre e Arquitetura

O PgArachne serve como um servidor web leve e de alta performance que fica entre os seus clientes HTTP e o banco de dados PostgreSQL. Ele elimina a necessidade de linguagens de backend tradicionais (como Python, Node.js ou PHP) mapeando requisições HTTP diretamente para funções do banco de dados.

Capacidades Técnicas Principais

Gateway JSON-RPC 2.0: Todas as interações da API seguem a especificação estrita JSON-RPC 2.0. Não há endpoints REST para projetar; você simplesmente chama funções SQL pelo nome via requisições POST.
Autenticação Nativa de BD: Sem tabelas de usuários separadas. Os usuários fazem login com suas credenciais reais do PostgreSQL para receber um JWT. Alternativamente, contas de serviço podem usar Tokens de API persistentes.
Mascaramento de Papéis (Role Masquerading): O PgArachne conecta-se como um usuário proxy, mas executa cada requisição usando SET LOCAL ROLE para mudar para a identidade do usuário autenticado. A segurança em nível de linha (Row-Level Security - RLS) funciona automaticamente.
Servidor de Arquivos Estáticos: O PgArachne pode servir ativos estáticos (HTML, JS, CSS), permitindo que você hospede Single Page Applications (SPAs) ou a ferramenta Explorer diretamente.

Esta arquitetura simplifica drasticamente a stack: Banco de Dados ↔ PgArachne ↔ Frontend.

Formato do Endpoint da API: Todas as funções do banco de dados são expostas em:

POST http://{servidor}:{porta}
/api
/{nome_do_banco}
/{nome_do_esquema}.{nome_da_funcao}

Instalação

Opção A: Baixar Binários

Baixe a versão pré-compilada mais recente para o seu sistema operacional:

Linux

x64/Intel/AMD ARM64/Aarch64

macOS

ARM64/Apple Silicon x64/Intel

Windows

x64/Intel/AMD ARM64

Opção B: Compilar do Código Fonte

git clone https://github.com/heptau/pgarachne.git
cd pgarachne
go build -o pgarachne cmd/pgarachne/main.go

Configuração do Banco de Dados

Inicialize o esquema pgarachne necessário para os tokens de API.

psql -d my_database -f sql/schema.sql

Configuração

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

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.

Ordem de Busca: Se nenhum arquivo de configuração for especificado via CLI, ele busca em:

Diretório atual: ./pgarachne.env (Todos os SOs)
Configuração do usuário:
- Linux / macOS: ~/.config/pgarachne/pgarachne.env
- Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
Configuração do sistema: /etc/pgarachne/pgarachne.env (Somente Linux / macOS)

Variável	Obrigatório	Descrição
Conexão com Banco de Dados
`DB_HOST`	Sim	Endereço do servidor PostgreSQL (ex: `localhost`).
`DB_PORT`	Não	Porta do banco de dados. Padrão: `5432`.
`DB_USER`	Sim	O usuário do banco de dados com o qual o PgArachne se conecta.
Servidor HTTP
`HTTP_PORT`	Não	Porta para escutar. Padrão: `8080`.
`ALLOWED_ORIGINS`	Não	Configurações de CORS. Lista separada por vírgulas de domínios permitidos (ex: `https://meuapp.com`). Padrão: `*`.
`STATIC_FILES_PATH`	Não	Caminho absoluto para servir arquivos estáticos (Explorer/Frontend).
Segurança (JWT)
`JWT_SECRET`	Sim	Uma string longa e aleatória usada para assinar tokens de sessão.
`JWT_EXPIRY_HOURS`	Não	Validade da sessão em horas. Padrão: `8`.
Logging
`LOG_LEVEL`	Não	Verbosidade: `DEBUG`, `INFO`, `WARN`, `ERROR`. Padrão: `INFO`.
`LOG_OUTPUT`	Não	Onde gravar logs: `stdout` ou caminho do arquivo.

Explorador PgArachne

O Explorer é uma interface web poderosa incluída no diretório `tools/`. Não é apenas documentação; é uma aplicação de demonstração totalmente funcional construída usando HTML/JS que se comunica com o banco de dados exclusivamente via PgArachne.

O que ele pode fazer?

Inspecionar API: Ele lê a função `capabilities` para exibir todos os endpoints disponíveis e seus parâmetros.
Testes ao Vivo: Você pode executar funções diretamente do navegador.
Autodocumentação: Ele renderiza os comentários SQL (incluindo metadados `--- PARAMS ---`) em documentação legível.

Como habilitá-lo: Defina a variável de ambiente `STATIC_FILES_PATH` para apontar para a pasta `tools/pgarachne-explorer` no seu disco. Em seguida, visite http://localhost:8080.

Segurança e Autenticação

O PgArachne depende inteiramente do sistema de permissões do PostgreSQL. Ele não reinventa Listas de Controle de Acesso (ACLs). Todas as consultas são executadas sob o papel de banco de dados específico do usuário autenticado usando SET LOCAL ROLE.

1. Login Interativo (JWT)

Os usuários se autenticam usando seu nome de usuário e senha reais do PostgreSQL via a função de login. Se bem-sucedido, eles recebem um JWT genérico. Quando este token é usado, o PgArachne muda o papel ativo para esse usuário pela duração da requisição.

2. Contas de Serviço (Tokens de API)

Para sistemas automatizados ou scripts, você pode usar chaves de API de longa duração.

Os tokens são armazenados na tabela pgarachne.api_tokens.
Cada token é mapeado para um usuário/papel de banco de dados específico.
Envie o token através do cabeçalho Authorization: Bearer <token>.

Configuração Crítica: Privilégios do Proxy

Como o PgArachne se conecta como o usuário definido em DB_USER (ex: pgarachne) e muda a identidade para outros usuários, o usuário proxy deve ser membro desses papéis alvo.

Execute este SQL para cada usuário/papel que precisa fazer login:

-- Permitir que 'pgarachne' mude para 'app_user'
GRANT app_user TO pgarachne;

Deployment e HTTPS

O PgArachne foi projetado para fazer uma coisa bem: API Gateway. Para SSL/TLS (HTTPS), segurança de cabeçalhos e roteamento público, você deve colocar um Proxy Reverso na frente dele.

Opção A: Caddy Server

Melhor para: Deployments de produção modernos, facilidade de uso.

Caddy é o único servidor web que obtém e renova certificados SSL (Let's Encrypt) automaticamente por padrão. Requer quase zero configuração.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opção B: Nginx

Melhor para: Ambientes corporativos, roteamento complexo.

Nginx é o padrão da indústria para balanceamento de carga de alta performance. Use isso se você já tem uma infraestrutura Nginx. Você precisará gerenciar o Certbot manualmente.

server {
    server_name example.com;
    location / {
        proxy_pass http://localhost:8080;
    }
}

Opção C: Ngrok

Melhor para: Desenvolvimento local, Demos, testes de Webhook.

Ngrok cria um túnel seguro da internet pública diretamente para o seu laptop sem configurar firewalls. Ideal para mostrar seu trabalho aos colegas instantaneamente.

./ngrok http 8080

Códigos de Erro

O PgArachne retorna objetos de erro padrão JSON-RPC 2.0. Abaixo estão os códigos específicos que você pode encontrar:

Código	Mensagem	Significado
`-32700`	Parse error	Um JSON inválido foi recebido pelo servidor.
`-32601`	Method not found	A função não existe no esquema.
`-32602`	Invalid params	Os argumentos não correspondem à assinatura da função.
`-32001`	Permission denied	O papel de usuário atual não tem privilégios para executar a função (nível BD).
`-32000`	Internal Error	Erro genérico do servidor (verifique os logs).

Apoie o Desenvolvimento

Desenvolver software open source como o PgArachne leva um tempo significativo. Se esta ferramenta economiza seu tempo, por favor, considere apoiar sua manutenção.

☕ Torne-se um Membro

Junte-se à comunidade no Buy Me a Coffee. Receba atualizações exclusivas, acesso antecipado a novos recursos e muito mais.

Apoiar no Buy Me a Coffee

Transferência Bancária

Apoio direto com 0% de taxas.

🇺🇸 ACH (EUA)

Nome

Zbynek Vanzura

Número da Conta

827908168786406

Tipo de Conta

Deposit

Número de Roteamento

084009519

Swift/BIC

TRWIUS35XXX

Endereço do Banco

Wise US Inc, 108 W 13th St, Wilmington, DE, 19801, United States

🇪🇺 SEPA (Euro)

Nome

Zbynek Vanzura

IBAN

BE68905813473834

Swift/BIC

TRWIBEB1XXX

Endereço do Banco

Wise, Rue du Trône 100, 3rd floor, Brussels, 1050, Belgium

🇨🇿 CZK (Tchéquia)

Nome

Zbynek Vanzura

Nº da Conta

2300354/2010

Criptomoeda

Apoio via ativos digitais.

Bitcoin (BTC)

Endereço BTC

bc1qw8swmnvk48lhcatyw55wz8g4gyjq3vkw0h78g6

USDT (TetherUS)

Endereço TRC20

TPemgxu8jxkjyiHpqrUJyc3dNEs3aPSb2T

Endereço ERC20

0xa689e1c6c8da09fcecca1b9733a22619f56288ff

Binance Pay

Doar via Binance Pay

Revolut

A maneira mais rápida de doar. Suporta Apple Pay, cartões de débito ou crédito.

Doar via Revolut

PayPal

Pagamentos fáceis e seguros. Suporta cartões de débito ou crédito.

Doar via PayPal

Wise

Pagamentos fáceis e seguros.

Doar via Wise

Licença e Marca Registrada

O Código (Licença MIT):
Você pode usar o código-fonte gratuitamente para qualquer projeto pessoal ou comercial. Você pode modificá-lo, fazer um fork e distribuí-lo.

A Marca (Marca Registrada):
O nome "PgArachne" e o Logo são marcas registradas de Zbyněk Vanžura. Se você fizer um fork do projeto ou oferecer um serviço comercial "Managed PgArachne", você deve remover a marca e o logo originais, a menos que tenha obtido uma licença especial.

O PgArachne é ideal para você?

🚀 Prototipagem Rápida

🏢 Pronto para Produção

🧠 Amigável para IA e LLM

Sobre e Arquitetura

Capacidades Técnicas Principais

Instalação

Opção A: Baixar Binários

Linux

macOS

Windows

Opção B: Compilar do Código Fonte

Configuração do Banco de Dados

Configuração

Explorador PgArachne

Segurança e Autenticação

1. Login Interativo (JWT)

2. Contas de Serviço (Tokens de API)

Configuração Crítica: Privilégios do Proxy

Deployment e HTTPS

Opção A: Caddy Server

Opção B: Nginx

Opção C: Ngrok

Códigos de Erro

Apoie o Desenvolvimento

☕ Torne-se um Membro

Transferência Bancária

Criptomoeda

Revolut

PayPal

Wise

Licença e Marca Registrada