PgArachne

Über & Architektur

PgArachne dient als leichter, hochleistungsfähiger Webserver, der zwischen Ihren HTTP-Clients und der PostgreSQL-Datenbank sitzt. Es eliminiert die Notwendigkeit für traditionelle Backend-Sprachen (wie Python, Node.js oder PHP), indem HTTP-Anfragen direkt auf Datenbankfunktionen abgebildet werden.

Wichtige technische Fähigkeiten

JSON-RPC 2.0 Gateway: Alle API-Interaktionen folgen der strengen JSON-RPC 2.0-Spezifikation. Es müssen keine REST-Endpunkte entworfen werden; Sie rufen SQL-Funktionen einfach per Namen über POST-Anfragen auf.
Native DB-Authentifizierung: Keine separaten Benutzertabellen. Benutzer melden sich mit ihren echten PostgreSQL-Anmeldeinformationen an, um ein JWT zu erhalten. Alternativ können Service-Konten persistente API-Token verwenden.
Rollen-Maskierung: PgArachne verbindet sich als Proxy-Benutzer, führt aber jede Anfrage mit SET LOCAL ROLE aus, um zur Identität des authentifizierten Benutzers zu wechseln. Row-Level Security (RLS) funktioniert automatisch.
Server für statische Dateien: PgArachne kann statische Assets (HTML, JS, CSS) bereitstellen, sodass Sie Single Page Applications (SPAs) oder das Explorer-Tool direkt hosten können.

Diese Architektur vereinfacht den Stack drastisch: Datenbank ↔ PgArachne ↔ Frontend.

API-Endpunkt-Format: Alle Datenbankfunktionen sind erreichbar unter:

POST http://{server}:{port}
/api
/{datenbank_name}
/{schema_name}.{funktions_name}

Installation

Option A: Binärdateien herunterladen

Laden Sie die neueste vorkompilierte Version für Ihr Betriebssystem herunter:

Linux

x64/Intel/AMD ARM64/Aarch64

macOS

ARM64/Apple Silicon x64/Intel

Windows

x64/Intel/AMD ARM64

Option B: Aus dem Quellcode kompilieren

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

Datenbank-Einrichtung

Initialisieren Sie das pgarachne-Schema, das für API-Token erforderlich ist.

psql -d my_database -f sql/schema.sql

Konfiguration

PgArachne lädt die Konfiguration aus Umgebungsvariablen oder einer Datei.

Sicherheitshinweis: PgArachne verarbeitet keine Datenbankpasswörter in der Konfigurationsdatei. Es verlässt sich auf den Standardmechanismus der .pgpass-Datei von PostgreSQL (oder die systemweite Variable PGPASSWORD) für die Authentifizierung.

Suchreihenfolge: Wenn keine Konfigurationsdatei über CLI angegeben ist, wird wie folgt gesucht:

Aktuelles Verzeichnis: ./pgarachne.env (Alle Betriebssysteme)
Benutzerkonfiguration:
- Linux / macOS: ~/.config/pgarachne/pgarachne.env
- Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
Systemkonfiguration: /etc/pgarachne/pgarachne.env (Nur Linux / macOS)

Variable	Erforderlich	Beschreibung
Datenbank-Verbindung
`DB_HOST`	Ja	PostgreSQL-Serveradresse (z.B. `localhost`).
`DB_PORT`	Nein	Datenbank-Port. Standard: `5432`.
`DB_USER`	Ja	Der Datenbankbenutzer, mit dem sich PgArachne verbindet.
HTTP-Server
`HTTP_PORT`	Nein	Port, auf dem gelauscht wird. Standard: `8080`.
`ALLOWED_ORIGINS`	Nein	CORS-Einstellungen. Kommagetrennte Liste zulässiger Domains (z.B. `https://meineapp.de`). Standard: `*`.
`STATIC_FILES_PATH`	Nein	Absoluter Pfad zum Bereitstellen statischer Dateien (Explorer/Frontend).
Sicherheit (JWT)
`JWT_SECRET`	Ja	Eine lange, zufällige Zeichenfolge zum Signieren von Sitzungstoken.
`JWT_EXPIRY_HOURS`	Nein	Gültigkeit der Sitzung in Stunden. Standard: `8`.
Logging
`LOG_LEVEL`	Nein	Ausführlichkeit: `DEBUG`, `INFO`, `WARN`, `ERROR`. Standard: `INFO`.
`LOG_OUTPUT`	Nein	Wohin Logs geschrieben werden: `stdout` oder Dateipfad.

PgArachne Explorer

Der Explorer ist eine leistungsstarke Web-GUI, die im Verzeichnis `tools/` enthalten ist. Es ist nicht nur Dokumentation; es ist eine voll funktionsfähige Demo-Anwendung, die mit HTML/JS erstellt wurde und ausschließlich über PgArachne mit der Datenbank kommuniziert.

Was kann er tun?

API inspizieren: Er liest die Funktion `capabilities`, um alle verfügbaren Endpunkte und deren Parameter anzuzeigen.
Live-Tests: Sie können Funktionen direkt im Browser ausführen.
Automatische Dokumentation: Er rendert die SQL-Kommentare (einschließlich `--- PARAMS ---` Metadaten) in eine lesbare Dokumentation.

So aktivieren Sie ihn: Setzen Sie die Umgebungsvariable `STATIC_FILES_PATH` so, dass sie auf den Ordner `tools/pgarachne-explorer` auf Ihrer Festplatte zeigt. Besuchen Sie dann http://localhost:8080.

Sicherheit & Authentifizierung

PgArachne verlässt sich vollständig auf das PostgreSQL-Berechtigungssystem. Es erfindet keine Access Control Lists (ACLs) neu. Alle Abfragen werden unter der spezifischen Datenbankrolle des authentifizierten Benutzers mit SET LOCAL ROLE ausgeführt.

1. Interaktives Login (JWT)

Benutzer authentifizieren sich über die Login-Funktion mit ihrem echten PostgreSQL-Benutzernamen und -Passwort. Bei Erfolg erhalten sie ein generisches JWT. Wenn dieses Token verwendet wird, wechselt PgArachne die aktive Rolle für die Dauer der Anfrage zu diesem Benutzer.

2. Service-Konten (API-Token)

Für automatisierte Systeme oder Skripte können Sie langlebige API-Schlüssel verwenden.

Token werden in der Tabelle pgarachne.api_tokens gespeichert.
Jedes Token ist einem bestimmten Datenbankbenutzer/-rolle zugeordnet.
Senden Sie das Token über den Header Authorization: Bearer <token>.

Kritische Konfiguration: Proxy-Privilegien

Da sich PgArachne als der in DB_USER definierte Benutzer (z.B. pgarachne) verbindet und die Identität zu anderen Benutzern wechselt, muss der Proxy-Benutzer Mitglied dieser Zielrollen sein.

Führen Sie dieses SQL für jeden Benutzer/jede Rolle aus, die sich anmelden muss:

-- Erlaube 'pgarachne' zu 'app_user' zu wechseln
GRANT app_user TO pgarachne;

Bereitstellung & HTTPS

PgArachne ist darauf ausgelegt, eine Aufgabe gut zu erfüllen: API Gateway. Für SSL/TLS (HTTPS), Header-Sicherheit und öffentliches Routing sollten Sie einen Reverse Proxy davor platzieren.

Option A: Caddy Server

Am besten für: Moderne Produktionsbereitstellungen, Benutzerfreundlichkeit.

Caddy ist der einzige Webserver, der standardmäßig automatisch SSL-Zertifikate (Let's Encrypt) bezieht und erneuert. Er erfordert fast keine Konfiguration.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Option B: Nginx

Am besten für: Unternehmensumgebungen, komplexes Routing.

Nginx ist der Industriestandard für hochleistungsfähiges Load Balancing. Verwenden Sie dies, wenn Sie bereits eine Nginx-Infrastruktur haben. Sie müssen Certbot manuell verwalten.

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

Option C: Ngrok

Am besten für: Lokale Entwicklung, Demos, Webhook-Tests.

Ngrok erstellt einen sicheren Tunnel vom öffentlichen Internet direkt zu Ihrem Laptop, ohne Firewalls zu konfigurieren. Ideal, um Kollegen Ihre Arbeit sofort zu zeigen.

./ngrok http 8080

Fehlercodes

PgArachne gibt standardmäßige JSON-RPC 2.0 Fehlerobjekte zurück. Unten finden Sie die spezifischen Codes, denen Sie begegnen können:

Code	Nachricht	Bedeutung
`-32700`	Parse error	Ungültiges JSON wurde vom Server empfangen.
`-32601`	Method not found	Die Funktion existiert nicht im schema.
`-32602`	Invalid params	Argumente stimmen nicht mit der Funktionssignatur überein.
`-32001`	Permission denied	Der aktuellen Benutzerrolle fehlen die Berechtigungen zum Ausführen der Funktion (DB-Ebene).
`-32000`	Internal Error	Allgemeiner Serverfehler (siehe Logs).

Unterstützen Sie die Entwicklung

Die Entwicklung von Open-Source-Software wie PgArachne erfordert viel Zeit. Wenn Ihnen dieses Tool Zeit spart, erwägen Sie bitte, seine Wartung zu unterstützen.

☕ Mitglied werden

Treten Sie der Community auf Buy Me a Coffee bei. Erhalten Sie exklusive Updates, früheren Zugang zu neuen Funktionen und mehr.

Unterstützen auf Buy Me a Coffee

Banküberweisung

Direkte Unterstützung mit 0% Gebühren.

🇺🇸 ACH (USA)

Name

Zbynek Vanzura

Kontonummer

827908168786406

Kontoart

Deposit

Routing-Nummer

084009519

Swift/BIC

TRWIUS35XXX

Bankadresse

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

🇪🇺 SEPA (Euro)

Name

Zbynek Vanzura

IBAN

BE68905813473834

Swift/BIC

TRWIBEB1XXX

Bankadresse

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

🇨🇿 CZK (Tschech. Rep.)

Name

Zbynek Vanzura

Kontonr.

2300354/2010

Kryptowährung

Unterstützung durch digitale Assets.

Bitcoin (BTC)

BTC Adresse

bc1qw8swmnvk48lhcatyw55wz8g4gyjq3vkw0h78g6

USDT (TetherUS)

TRC20 Adresse

TPemgxu8jxkjyiHpqrUJyc3dNEs3aPSb2T

ERC20 Adresse

0xa689e1c6c8da09fcecca1b9733a22619f56288ff

Binance Pay

Spenden via Binance Pay

Revolut

Der schnellste Weg zu spenden. Unterstützt Apple Pay, Debit- oder Kreditkarten.

Spenden via Revolut

PayPal

Einfache sichere Zahlungen. Unterstützt Debit- oder Kreditkarten.

Spenden via PayPal

Wise

Einfache sichere Zahlungen.

Spenden via Wise

Lizenz & Markenrecht

Der Code (MIT Lizenz):
Sie können den Quellcode kostenlos für jedes persönliche oder kommerzielle Projekt verwenden. Sie können ihn ändern, forken und verbreiten.

Die Marke (Markenrecht):
Der Name "PgArachne" und das Logo sind Marken von Zbyněk Vanžura. Wenn Sie das Projekt forken oder einen kommerziellen "Managed PgArachne"-Dienst anbieten, müssen Sie das ursprüngliche Branding und das Logo entfernen, es sei denn, Sie haben eine spezielle Lizenz erhalten.

Ist PgArachne das Richtige für Sie?

🚀 Schnelles Prototyping

🏢 Produktionsbereit

🧠 KI- & LLM-freundlich

Über & Architektur

Wichtige technische Fähigkeiten

Installation

Option A: Binärdateien herunterladen

Linux

macOS

Windows

Option B: Aus dem Quellcode kompilieren

Datenbank-Einrichtung

Konfiguration

PgArachne Explorer

Sicherheit & Authentifizierung

1. Interaktives Login (JWT)

2. Service-Konten (API-Token)

Kritische Konfiguration: Proxy-Privilegien

Bereitstellung & HTTPS

Option A: Caddy Server

Option B: Nginx

Option C: Ngrok

Fehlercodes

Unterstützen Sie die Entwicklung

☕ Mitglied werden

Banküberweisung

Kryptowährung

Revolut

PayPal

Wise

Lizenz & Markenrecht