PgArachne

Chi siamo e Architettura

PgArachne funge da server web leggero e ad alte prestazioni che si interpone tra i tuoi client HTTP e il database PostgreSQL. Elimina la necessità di linguaggi backend tradizionali (come Python, Node.js o PHP) mappando le richieste HTTP direttamente alle funzioni del database.

Capacità Tecniche Principali

Gateway JSON-RPC 2.0: Tutte le interazioni API seguono la rigorosa specifica JSON-RPC 2.0. Non ci sono endpoint REST da progettare; chiami semplicemente le funzioni SQL per nome tramite richieste POST.
Autenticazione Nativa DB: Nessuna tabella utenti separata. Gli utenti accedono con le loro reali credenziali PostgreSQL per ricevere un JWT. In alternativa, gli account di servizio possono utilizzare Token API persistenti.
Mascheramento dei Ruoli: PgArachne si connette come utente proxy ma esegue ogni richiesta utilizzando SET LOCAL ROLE per passare all'identità dell'utente autenticato. La sicurezza a livello di riga (Row-Level Security - RLS) funziona automaticamente.
Server di File Statici: PgArachne può servire asset statici (HTML, JS, CSS), consentendoti di ospitare Single Page Application (SPA) o lo strumento Explorer direttamente.

Questa architettura semplifica drasticamente lo stack: Database ↔ PgArachne ↔ Frontend.

Formato Endpoint API: Tutte le funzioni del database sono esposte su:

POST http://{server}:{porta}
/api
/{nome_database}
/{nome_schema}.{nome_funzione}

Installazione

Opzione A: Scarica i Binari

Scarica l'ultima versione precompilata per il tuo sistema operativo:

Linux

x64/Intel/AMD ARM64/Aarch64

macOS

ARM64/Apple Silicon x64/Intel

Windows

x64/Intel/AMD ARM64

Opzione B: Compila dal Codice Sorgente

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

Configurazione Database

Inizializza lo schema pgarachne richiesto per i token API.

psql -d my_database -f sql/schema.sql

Configurazione

PgArachne carica la configurazione dalle variabili d'ambiente o da un file.

Nota di Sicurezza: PgArachne non gestisce le password del database nel file di configurazione. Si affida al meccanismo standard del file .pgpass di PostgreSQL (o alla variabile di sistema PGPASSWORD) per l'autenticazione.

Ordine di Ricerca: Se nessun file di configurazione è specificato via CLI, cerca in:

Directory corrente: ./pgarachne.env (Tutti i SO)
Configurazione utente:
- Linux / macOS: ~/.config/pgarachne/pgarachne.env
- Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
Configurazione di sistema: /etc/pgarachne/pgarachne.env (Solo Linux / macOS)

Variabile	Richiesto	Descrizione
Connessione Database
`DB_HOST`	Sì	Indirizzo del server PostgreSQL (es. `localhost`).
`DB_PORT`	No	Porta del database. Default: `5432`.
`DB_USER`	Sì	L'utente del database con cui PgArachne si connette.
Server HTTP
`HTTP_PORT`	No	Porta su cui ascoltare. Default: `8080`.
`ALLOWED_ORIGINS`	No	Impostazioni CORS. Elenco separato da virgole dei domini consentiti (es. `https://miapp.com`). Default: `*`.
`STATIC_FILES_PATH`	No	Percorso assoluto per servire file statici (Explorer/Frontend).
Sicurezza (JWT)
`JWT_SECRET`	Sì	Una stringa lunga e casuale usata per firmare i token di sessione.
`JWT_EXPIRY_HOURS`	No	Validità della sessione in ore. Default: `8`.
Logging
`LOG_LEVEL`	No	Verbosità: `DEBUG`, `INFO`, `WARN`, `ERROR`. Default: `INFO`.
`LOG_OUTPUT`	No	Dove scrivere i log: `stdout` o percorso del file.

PgArachne Explorer

L'Explorer è una potente interfaccia web inclusa nella directory `tools/`. Non è solo documentazione; è una **applicazione demo** completamente funzionale costruita usando HTML/JS che comunica con il database esclusivamente tramite PgArachne.

Cosa può fare?

Ispezionare API: Legge la funzione `capabilities` per mostrare tutti gli endpoint disponibili e i loro parametri.
Test dal Vivo: Puoi eseguire le funzioni direttamente dal browser.
Auto-Documentazione: Renderizza i commenti SQL (inclusi i metadati `--- PARAMS ---`) in una documentazione leggibile.

Come abilitarlo: Imposta la variabile d'ambiente `STATIC_FILES_PATH` in modo che punti alla cartella `tools/pgarachne-explorer` sul tuo disco. Poi visita http://localhost:8080.

Sicurezza e Autenticazione

PgArachne si affida interamente al sistema di permessi di PostgreSQL. Non reinventa le Liste di Controllo degli Accessi (ACL). Tutte le query vengono eseguite sotto il ruolo database specifico dell'utente autenticato utilizzando SET LOCAL ROLE.

1. Login Interattivo (JWT)

Gli utenti si autenticano utilizzando il loro reale nome utente e password PostgreSQL tramite la funzione di login. In caso di successo, ricevono un JWT generico. Quando questo token viene utilizzato, PgArachne cambia il ruolo attivo in quell'utente per la durata della richiesta.

2. Account di Servizio (Token API)

Per sistemi automatizzati o script, puoi utilizzare chiavi API a lunga durata.

I token sono memorizzati nella tabella pgarachne.api_tokens.
Ogni token è mappato a un utente/ruolo database specifico.
Invia il token tramite l'header Authorization: Bearer <token>.

Configurazione Critica: Privilegi Proxy

Poiché PgArachne si connette come l'utente definito in DB_USER (es. pgarachne) e cambia identità in altri utenti, l'utente proxy deve essere membro di quei ruoli di destinazione.

Esegui questo SQL per ogni utente/ruolo che deve accedere:

-- Consenti a 'pgarachne' di passare a 'app_user'
GRANT app_user TO pgarachne;

Deployment e HTTPS

PgArachne è progettato per svolgere bene un solo compito: API Gateway. Per SSL/TLS (HTTPS), sicurezza degli header e routing pubblico, dovresti posizionare un Reverse Proxy davanti ad esso.

Opzione A: Server Caddy

Ideale per: Deployment di produzione moderni, facilità d'uso.

Caddy è l'unico server web che ottiene e rinnova automaticamente i certificati SSL (Let's Encrypt) per impostazione predefinita. Richiede quasi zero configurazione.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opzione B: Nginx

Ideale per: Ambienti enterprise, routing complesso.

Nginx è lo standard industriale per il bilanciamento del carico ad alte prestazioni. Usalo se hai già un'infrastruttura Nginx. Dovrai gestire Certbot manualmente.

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

Opzione C: Ngrok

Ideale per: Sviluppo locale, Demo, test Webhook.

Ngrok crea un tunnel sicuro da internet pubblico direttamente al tuo portatile senza configurare firewall. Ideale per mostrare il tuo lavoro ai colleghi all'istante.

./ngrok http 8080

Codici di Errore

PgArachne restituisce oggetti di errore standard JSON-RPC 2.0. Di seguito sono riportati i codici specifici che potresti incontrare:

Codice	Messaggio	Significato
`-32700`	Parse error	Il server ha ricevuto JSON non valido.
`-32601`	Method not found	La funzione non esiste nello schema.
`-32602`	Invalid params	Gli argomenti non corrispondono alla firma della funzione.
`-32001`	Permission denied	Il ruolo utente corrente non ha i privilegi per eseguire la funzione (livello DB).
`-32000`	Internal Error	Errore generico del server (controlla i log).

Sostieni lo Sviluppo

Sviluppare software open source come PgArachne richiede molto tempo. Se questo strumento ti fa risparmiare tempo, ti preghiamo di considerare di sostenerne la manutenzione.

☕ Diventa un Membro

Unisciti alla community su Buy Me a Coffee. Ottieni aggiornamenti esclusivi, accesso anticipato alle nuove funzionalità e altro ancora.

Sostieni su Buy Me a Coffee

Bonifico Bancario

Supporto diretto con 0% di commissioni.

🇺🇸 ACH (USA)

Nome

Zbynek Vanzura

Numero Conto

827908168786406

Tipo Conto

Deposit

Routing Number

084009519

Swift/BIC

TRWIUS35XXX

Indirizzo Banca

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

🇪🇺 SEPA (Euro)

Nome

Zbynek Vanzura

IBAN

BE68905813473834

Swift/BIC

TRWIBEB1XXX

Indirizzo Banca

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

🇨🇿 CZK (Cechia)

Nome

Zbynek Vanzura

Numero Conto

2300354/2010

Criptovaluta

Supporto tramite asset digitali.

Bitcoin (BTC)

Indirizzo BTC

bc1qw8swmnvk48lhcatyw55wz8g4gyjq3vkw0h78g6

USDT (TetherUS)

Indirizzo TRC20

TPemgxu8jxkjyiHpqrUJyc3dNEs3aPSb2T

Indirizzo ERC20

0xa689e1c6c8da09fcecca1b9733a22619f56288ff

Binance Pay

Dona tramite Binance Pay

Revolut

Il modo più veloce per donare. Supporta Apple Pay, carte di debito o credito.

Dona tramite Revolut

PayPal

Pagamenti facili e sicuri. Supporta carte di debito o credito.

Dona tramite PayPal

Wise

Pagamenti facili e sicuri.

Dona tramite Wise

Licenza e Marchio

Il Codice (Licenza MIT):
Puoi utilizzare il codice sorgente gratuitamente per qualsiasi progetto personale o commerciale. Puoi modificarlo, farne un fork e distribuirlo.

Il Marchio (Trademark):
Il nome "PgArachne" e il Logo sono marchi registrati di Zbyněk Vanžura. Se fai un fork del progetto o offri un servizio commerciale "Managed PgArachne", devi rimuovere il marchio e il logo originali a meno che tu non abbia ottenuto una licenza speciale.

PgArachne fa al caso tuo?

🚀 Prototipazione Rapida

🏢 Pronto per la Produzione

🧠 Ideale per IA e LLM

Chi siamo e Architettura

Capacità Tecniche Principali

Installazione

Opzione A: Scarica i Binari

Linux

macOS

Windows

Opzione B: Compila dal Codice Sorgente

Configurazione Database

Configurazione

PgArachne Explorer

Sicurezza e Autenticazione

1. Login Interattivo (JWT)

2. Account di Servizio (Token API)

Configurazione Critica: Privilegi Proxy

Deployment e HTTPS

Opzione A: Server Caddy

Opzione B: Nginx

Opzione C: Ngrok

Codici di Errore

Sostieni lo Sviluppo

☕ Diventa un Membro

Bonifico Bancario

Criptovaluta

Revolut

PayPal

Wise

Licenza e Marchio