PgArachne

À propos & Architecture

PgArachne sert de serveur web léger et haute performance qui se place entre vos clients HTTP et la base de données PostgreSQL. Il élimine le besoin de langages backend traditionnels (comme Python, Node.js ou PHP) en mappant les requêtes HTTP directement aux fonctions de la base de données.

Capacités Techniques Principales

Passerelle JSON-RPC 2.0 : Toutes les interactions API suivent la spécification stricte JSON-RPC 2.0. Il n'y a pas d'endpoints REST à concevoir ; vous appelez simplement les fonctions SQL par leur nom via des requêtes POST.
Authentification Native BDD : Pas de tables utilisateurs séparées. Les utilisateurs se connectent avec leurs identifiants PostgreSQL réels pour recevoir un JWT. Alternativement, les comptes de service peuvent utiliser des Tokens API persistants.
Masquage de Rôle : PgArachne se connecte en tant qu'utilisateur proxy mais exécute chaque requête en utilisant SET LOCAL ROLE pour basculer vers l'identité de l'utilisateur authentifié. La sécurité au niveau des lignes (RLS) fonctionne automatiquement.
Serveur de Fichiers Statiques : PgArachne peut servir des assets statiques (HTML, JS, CSS), vous permettant d'héberger des applications monopage (SPA) ou l'outil Explorer directement.

Cette architecture simplifie considérablement la stack : Base de données ↔ PgArachne ↔ Frontend.

Format de l'Endpoint API : Toutes les fonctions de la base de données sont exposées sur :

POST http://{serveur}:{port}
/api
/{nom_base_de_donnees}
/{nom_schema}.{nom_fonction}

Installation

Option A : Télécharger les binaires

Téléchargez la dernière version précompilée pour votre système d'exploitation :

Linux

x64/Intel/AMD ARM64/Aarch64

macOS

ARM64/Apple Silicon x64/Intel

Windows

x64/Intel/AMD ARM64

Option B : Compiler depuis la source

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

Configuration de la base de données

Initialisez le schéma pgarachne requis pour les tokens API.

psql -d my_database -f sql/schema.sql

Configuration

PgArachne charge la configuration depuis des variables d'environnement ou un fichier.

Note de sécurité : PgArachne ne gère pas les mots de passe de la base de données dans le fichier de configuration. Il s'appuie sur le mécanisme standard du fichier .pgpass de PostgreSQL (ou la variable système PGPASSWORD) pour l'authentification.

Ordre de recherche : Si aucun fichier de configuration n'est spécifié via CLI, il cherche :

Répertoire actuel : ./pgarachne.env (Tous les OS)
Configuration utilisateur :
- Linux / macOS : ~/.config/pgarachne/pgarachne.env
- Windows : %USERPROFILE%\.config\pgarachne\pgarachne.env
Configuration système : /etc/pgarachne/pgarachne.env (Linux / macOS uniquement)

Variable	Requis	Description
Connexion Base de Données
`DB_HOST`	Oui	Adresse du serveur PostgreSQL (ex: `localhost`).
`DB_PORT`	Non	Port de la base de données. Défaut : `5432`.
`DB_USER`	Oui	L'utilisateur de base de données avec lequel PgArachne se connecte.
Serveur HTTP
`HTTP_PORT`	Non	Port d'écoute. Défaut : `8080`.
`ALLOWED_ORIGINS`	Non	Paramètres CORS. Liste séparée par des virgules des domaines autorisés (ex: `https://monapp.com`). Défaut : `*`.
`STATIC_FILES_PATH`	Non	Chemin absolu pour servir les fichiers statiques (Explorer/Frontend).
Sécurité (JWT)
`JWT_SECRET`	Oui	Une longue chaîne aléatoire utilisée pour signer les jetons de session.
`JWT_EXPIRY_HOURS`	Non	Validité de la session en heures. Défaut : `8`.
Logging
`LOG_LEVEL`	Non	Verbosité : `DEBUG`, `INFO`, `WARN`, `ERROR`. Défaut : `INFO`.
`LOG_OUTPUT`	Non	Où écrire les logs : `stdout` ou chemin du fichier.

Explorateur PgArachne

L'Explorer est une interface web puissante incluse dans le répertoire `tools/`. Ce n'est pas seulement de la documentation ; c'est une application de démonstration entièrement fonctionnelle construite en HTML/JS qui communique avec la base de données exclusivement via PgArachne.

Que peut-il faire ?

Inspecter l'API : Il lit la fonction `capabilities` pour afficher tous les endpoints disponibles et leurs paramètres.
Tests en direct : Vous pouvez exécuter des fonctions directement depuis le navigateur.
Auto-Documentation : Il rend les commentaires SQL (y compris les métadonnées `--- PARAMS ---`) en documentation lisible.

Comment l'activer : Définissez la variable d'environnement `STATIC_FILES_PATH` pour pointer vers le dossier `tools/pgarachne-explorer` sur votre disque. Puis visitez http://localhost:8080.

Sécurité & Authentification

PgArachne s'appuie entièrement sur le système de permission de PostgreSQL. Il ne réinvente pas les listes de contrôle d'accès (ACL). Toutes les requêtes sont exécutées sous le rôle de base de données spécifique de l'utilisateur authentifié en utilisant SET LOCAL ROLE.

1. Connexion interactive (JWT)

Les utilisateurs s'authentifient en utilisant leur vrai nom d'utilisateur et mot de passe PostgreSQL via la fonction de connexion. En cas de succès, ils reçoivent un JWT générique. Lorsque ce jeton est utilisé, PgArachne bascule le rôle actif vers cet utilisateur pour la durée de la requête.

2. Comptes de service (Tokens API)

Pour les systèmes automatisés ou les scripts, vous pouvez utiliser des clés API longue durée.

Les jetons sont stockés dans la table pgarachne.api_tokens.
Chaque jeton est mappé à un utilisateur/rôle de base de données spécifique.
Envoyez le jeton via l'en-tête Authorization: Bearer <token>.

Configuration critique : Privilèges Proxy

Puisque PgArachne se connecte en tant qu'utilisateur défini dans DB_USER (ex: pgarachne) et bascule l'identité vers d'autres utilisateurs, l'utilisateur proxy doit être membre de ces rôles cibles.

Exécutez ce SQL pour chaque utilisateur/rôle qui doit se connecter :

-- Autoriser 'pgarachne' à basculer vers 'app_user'
GRANT app_user TO pgarachne;

Déploiement & HTTPS

PgArachne est conçu pour faire une seule tâche bien : API Gateway. Pour le SSL/TLS (HTTPS), la sécurité des en-têtes et le routage public, vous devriez placer un Reverse Proxy devant.

Option A : Serveur Caddy

Idéal pour : Déploiements de production modernes, facilité d'utilisation.

Caddy est le seul serveur web qui obtient et renouvelle les certificats SSL (Let's Encrypt) automatiquement par défaut. Il ne nécessite presque aucune configuration.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Option B : Nginx

Idéal pour : Environnements d'entreprise, routage complexe.

Nginx est la norme industrielle pour l'équilibrage de charge (load balancing) haute performance. Utilisez-le si vous avez déjà une infrastructure Nginx. Vous devrez gérer Certbot manuellement.

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

Option C : Ngrok

Idéal pour : Développement local, Démos, tests de Webhook.

Ngrok crée un tunnel sécurisé depuis l'internet public directement vers votre ordinateur portable sans configurer de pare-feu. Idéal pour montrer votre travail à des collègues instantanément.

./ngrok http 8080

Codes d'erreur

PgArachne renvoie des objets d'erreur standard JSON-RPC 2.0. Voici les codes spécifiques que vous pouvez rencontrer :

Code	Message	Signification
`-32700`	Parse error	Un JSON invalide a été reçu par le serveur.
`-32601`	Method not found	La fonction n'existe pas dans le schéma.
`-32602`	Invalid params	Les arguments ne correspondent pas à la signature de la fonction.
`-32001`	Permission denied	Le rôle utilisateur actuel manque de privilèges pour exécuter la fonction (niveau DB).
`-32000`	Internal Error	Erreur générique du serveur (vérifiez les logs).

Soutenir le développement

Le développement de logiciels open-source comme PgArachne prend beaucoup de temps. Si cet outil vous fait gagner du temps, veuillez envisager de soutenir sa maintenance.

☕ Devenir membre

Rejoignez la communauté sur Buy Me a Coffee. Obtenez des mises à jour exclusives, un accès anticipé aux nouvelles fonctionnalités, et plus encore.

Soutenir sur Buy Me a Coffee

Virement bancaire

Soutien direct avec 0% de frais.

🇺🇸 ACH (USA)

Nom

Zbynek Vanzura

Numéro de compte

827908168786406

Type de compte

Deposit

Routing Number

084009519

Swift/BIC

TRWIUS35XXX

Adresse de la banque

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

🇪🇺 SEPA (Euro)

Nom

Zbynek Vanzura

IBAN

BE68905813473834

Swift/BIC

TRWIBEB1XXX

Adresse de la banque

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

🇨🇿 CZK (Tchéquie)

Nom

Zbynek Vanzura

Numéro de compte

2300354/2010

Cryptomonnaie

Soutien via actifs numériques.

Bitcoin (BTC)

Adresse BTC

bc1qw8swmnvk48lhcatyw55wz8g4gyjq3vkw0h78g6

USDT (TetherUS)

Adresse TRC20

TPemgxu8jxkjyiHpqrUJyc3dNEs3aPSb2T

Adresse ERC20

0xa689e1c6c8da09fcecca1b9733a22619f56288ff

Binance Pay

Faire un don via Binance Pay

Revolut

Le moyen le plus rapide de faire un don. Supporte Apple Pay, cartes de débit ou crédit.

Faire un don via Revolut

PayPal

Paiements faciles et sécurisés. Supporte cartes de débit ou crédit.

Faire un don via PayPal

Wise

Paiements faciles et sécurisés.

Faire un don via Wise

Licence & Marque déposée

Le Code (Licence MIT) :
Vous pouvez utiliser le code source gratuitement pour tout projet personnel ou commercial. Vous pouvez le modifier, le forker et le distribuer.

La Marque (Marque déposée) :
Le nom "PgArachne" et le Logo sont des marques déposées de Zbyněk Vanžura. Si vous forkez le projet ou offrez un service commercial "Managed PgArachne", vous devez supprimer la marque et le logo originaux à moins d'avoir obtenu une licence spéciale.

PgArachne est-il fait pour vous ?

🚀 Prototypage Rapide

🏢 Prêt pour la Production

🧠 Adapté à l'IA & aux LLM

À propos & Architecture

Capacités Techniques Principales

Installation

Option A : Télécharger les binaires

Linux

macOS

Windows

Option B : Compiler depuis la source

Configuration de la base de données

Configuration

Explorateur PgArachne

Sécurité & Authentification

1. Connexion interactive (JWT)

2. Comptes de service (Tokens API)

Configuration critique : Privilèges Proxy

Déploiement & HTTPS

Option A : Serveur Caddy

Option B : Nginx

Option C : Ngrok

Codes d'erreur

Soutenir le développement

☕ Devenir membre

Virement bancaire

Cryptomonnaie

Revolut

PayPal

Wise

Licence & Marque déposée