Configuration

6 min de lecture

Démarrage rapide

  1. Installez PgArachne
  2. Configurez l’environnement
  3. Configurez sécurité et auth
  4. Déployez derrière un proxy HTTPS

Configuration

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

Note : schema.sql tente de créer le rôle pgarachne_admin et de l’accorder à pgarachne. Sans droits superuser, la création est ignorée. Créez le rôle et le grant manuellement si besoin.
L’utilisateur proxy (DB_USER) doit être membre de pgarachne et pgarachne_admin pour vérifier et créer des tokens API.
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.
Astuce : Si PgArachne est derrière un reverse proxy, définissez TRUSTED_PROXIES pour résoudre correctement l’adresse IP du client et éviter le contournement du rate limit.
Ordre de recherche : Si aucun fichier de configuration n’est spécifié via CLI, il cherche :
  1. Répertoire actuel : ./pgarachne.env (Tous les OS)
  2. Configuration utilisateur :
    • Linux/macOS : ~/.config/pgarachne/pgarachne.env
    • Windows : %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Configuration système : /etc/pgarachne/pgarachne.env (Linux/macOS uniquement)

Exemple de configuration minimale

Voici tout ce dont vous avez besoin pour commencer :

DB_HOST=localhost
DB_PORT=5432
DB_USER=pgarachne
# Optional — enables JWT sessions (POST /db//token) :
# JWT_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Variables requises : DB_HOST, DB_PORT, DB_USER.

JWT_SECRET est optionnel. Définissez-le (minimum 32 octets ; générez-le avec openssl rand -hex 32) pour activer les sessions JWT via POST /{prefix}/{database}/token ainsi que les JWT émis par un service externe. Sans lui, la prise en charge des JWT est désactivée et les clients s’authentifient avec des identifiants HTTP Basic (nom d’utilisateur et mot de passe de la base de données) ou des tokens API longue durée.

Checklist rapide de validation

  • Si JWT est activé, JWT_SECRET est long, aléatoire et différent selon les environnements.
  • DB_USER ne peut basculer que vers les rôles attendus (vérifier les grants de membership).
  • TRUSTED_PROXIES est défini si PgArachne est derrière un reverse proxy.
  • LOGIN_RATE_LIMIT est activé pour les déploiements exposés à internet.
  • METRICS_LISTEN_ADDR reste privé (par exemple 127.0.0.1:9090).

Référence de configuration

VariableRequisDescription
Connexion Base de Données
DB_HOST✓Adresse du serveur PostgreSQL (ex : localhost).
DB_PORT✓Port de la base de données.
DB_USER✓L’utilisateur de base de données avec lequel PgArachne se connecte.
DB_SSLMODE○Mode SSL PostgreSQL. Par défaut : require. Ne définissez disable explicitement que pour le développement local contre un PostgreSQL sans TLS.
DB_SSLROOTCERT○Chemin vers le certificat racine CA (PEM).
DB_SSLCERT○Chemin vers le certificat client (PEM).
DB_SSLKEY○Chemin vers la clé privée du client (PEM).
Serveur HTTP
HTTP_PORT○Port d’écoute. Défaut : 8080.
API_PREFIX○Premier segment du chemin URL pour tous les endpoints de base de données (/jsonrpc, /file, /sse, /mcp). Par défaut : db, donnant des routes comme /db/:base_de_donnees/jsonrpc. Seules les lettres, chiffres, tirets et underscores sont autorisés.
PID_FILE○Chemin du fichier PID du daemon utilisé par -start/-stop. Par défaut : cache utilisateur (fallback : dossier temporaire).
ALLOWED_ORIGINS○Paramètres CORS. Liste séparée par des virgules des domaines autorisés (ex : https://monapp.com). Par défaut : non défini — les requêtes cross-origin du navigateur sont désactivées. Définissez * explicitement pour autoriser toute origine.
STATIC_FILES_PATH○Chemin absolu pour servir les fichiers statiques (Explorer/Frontend).
Sécurité (JWT & connexion)
JWT_SECRET○Une longue chaîne aléatoire utilisée pour signer les jetons de session. Au moins 32 octets ; générez-le avec openssl rand -hex 32. S’il n’est pas défini, la prise en charge des JWT est désactivée : l’endpoint /token n’est pas disponible et les clients s’authentifient uniquement avec des identifiants HTTP Basic ou des tokens API.
JWT_EXPIRY_HOURS○Validité de la session en heures (doit être supérieure à 0). Défaut : 8.
JWT_ISSUER○Si défini, écrit dans le claim iss et doit correspondre exactement lors de la validation. Vide = pas de vérification.
JWT_AUDIENCE○Si défini, écrit dans le claim aud et doit correspondre lors de la validation. Vide = pas de vérification.
JWT_LEEWAY○Tolérance d’horloge pour exp/nbf/iat (ex. 30s). Par défaut : 30s.
LOGIN_RATE_LIMIT○Nombre maximum de tentatives d’authentification par IP client et par nom d’utilisateur, par fenêtre. S’applique à toutes les méthodes de connexion : chaque requête vers /token compte et, pour les identifiants HTTP Basic (sur tous les endpoints), les tentatives échouées comptent. Par défaut : 5. 0 désactive.
LOGIN_RATE_LIMIT_PER_IP○Nombre maximum de tentatives d’authentification par IP client, tous noms d’utilisateur confondus, afin que la rotation des noms ne contourne pas la limite. Compte aussi les tentatives Bearer échouées (JWT ou token API invalide). Par défaut : 5× LOGIN_RATE_LIMIT. 0 désactive.
LOGIN_RATE_WINDOW○Durée de la fenêtre de limitation. Par défaut : 1m.
Le rate limit de login est par instance (en mémoire). En multi-instance, utilisez un limiteur partagé.
TRUSTED_PROXIES○Proxys de confiance (IP/CIDR) pour X-Forwarded-For. Séparés par des virgules. Si vide, les en-têtes forwardés sont ignorés et l’IP client est prise depuis la connexion directe.
FILE_MAX_BYTES○Taille totale décompressée maximale d’une réponse /file en octets. Par défaut : 67108864 (64 Mio).
FILE_MAX_ENTRIES○Nombre maximal de fichiers dans une réponse /file. Par défaut : 1000.
MAX_REQUEST_BYTES○Taille maximale du body en octets. Par défaut : 2097152.
MCP_SQL_ERROR_DETAIL○Inclure le message d’erreur PostgreSQL brut dans les erreurs des outils MCP. Les erreurs détaillées aident les agents LLM à s’autocorriger, mais peuvent exposer des détails du schéma (noms de tables et de contraintes) aux appelants authentifiés. Par défaut : false.
DIRECT_POOL_LIMIT○Nombre maximum de pools de connexion distincts pour les identifiants Basic Auth. Par défaut : 1000.
METRICS_ENABLED○Active le endpoint dédié aux métriques. Par défaut : true.
METRICS_LISTEN_ADDR○Adresse du listener de métriques (host:port). Par défaut : 127.0.0.1:9090.
SSE_MAX_CHANNELS○Nombre maximal de canaux par connexion SSE. Par défaut : 8.
SSE_MAX_CLIENTS○Nombre maximal de clients SSE simultanés par base. Par défaut : 1000.
SSE_CLIENT_BUFFER○Buffer SSE par client (nombre de messages). Par défaut : 64.
SSE_SEND_TIMEOUT○Délai max pour envoyer à un client lent. Par défaut : 2s.
SSE_HEARTBEAT○Intervalle de heartbeat pour SSE. Par défaut : 20s.
SSE_IDLE_TIMEOUT○Délai d’inactivité sans notifications. Par défaut : 90s.
Logging
LOG_LEVEL○Verbosité : DEBUG, INFO, WARN, ERROR. Défaut : INFO.
LOG_OUTPUT○Où écrire les logs : stdout ou chemin du fichier.

Obligatoire   Optionnel

Comportement de sécurité : les requêtes sans en-tête Authorization valide sont rejetées avant l’ouverture d’une connexion à la base.

Démarrez le serveur :

./pgarachne -config .env

Documentation liée

← Installation JSON-RPC →