Logo PgArachne

PgArachne

Proměňte PostgreSQL v bezpečné API. Okamžitě.

Žádný zbytečný kód. Vysoký výkon. Middleware, který mapuje HTTP požadavky přímo na databázové funkce.

Začínáme GitHub Zobrazit demo (Explorer)

Je PgArachne pro vás to pravé?

PgArachne není jen pro prototypování.
Překlenuje propast mezi hrubým výkonem databáze a požadavky moderních API.

🚀 Rychlé prototypování

Přestaňte psát opakující se CRUD controllery. Definujte SQL funkci a váš API endpoint je okamžitě hotový. Ideální pro MVP a hackathony.

🏢 Připraven pro produkci

Navržen tak, aby zvládal více než 90 % standardních backendových úloh (CRUD, validace, auth). Díky poolování připojení, bezpečnému vypínání a metrikám Prometheus spolehlivě pohání produkční systémy.

🧠 Vhodné pro AI a LLM

Jelikož API se samo dokumentuje pomocí SQL komentářů, můžete schéma předhodit přímo LLM (ChatGPT, Claude). To umožňuje AI agentům pochopit vaši business logiku a vytvářet platná volání API bez halucinací.

O projektu a architektuře

PgArachne slouží jako lehký, vysoce výkonný webový server, který stojí mezi vašimi HTTP klienty a databází PostgreSQL. Eliminuje potřebu tradičních backendových jazyků (jako Python, Node.js nebo PHP) tím, že mapuje HTTP požadavky přímo na databázové funkce.

Klíčové technické schopnosti

  • Brána JSON-RPC 2.0: Veškeré interakce s API se řídí striktní specifikací JSON-RPC 2.0. Nemusíte navrhovat žádné REST endpointy; jednoduše voláte SQL funkce jménem pomocí POST požadavků.
  • Nativní DB autentizace: Žádné oddělené tabulky uživatelů. Uživatelé se přihlašují svými skutečnými PostgreSQL přihlašovacími údaji a získají JWT. Služby mohou alternativně využívat trvalé API Tokeny.
  • Maskování rolí (Role Masquerading): PgArachne se připojuje jako proxy uživatel, ale každý požadavek provádí pomocí SET LOCAL ROLE, čímž se přepne do identity ověřeného uživatele. Zabezpečení na úrovni řádků (RLS) funguje automaticky.
  • Server statických souborů: PgArachne může servírovat statické assety (HTML, JS, CSS), což vám umožní hostovat Single Page Aplikace (SPA) nebo přímo nástroj Explorer.

Tato architektura dramaticky zjednodušuje stack: Databáze ↔ PgArachne ↔ Frontend.

Formát API endpointu: Všechny databázové funkce jsou vystaveny na:
POST http://{server}:{port}
/api
/{nazev_databaze}
/{nazev_schema}.{nazev_funkce}

Instalace

Možnost A: Stáhnout binární soubory

Stáhněte si nejnovější předkompilovanou verzi pro váš operační systém:

Linux

x64/Intel/AMD ARM64/Aarch64

macOS

ARM64/Apple Silicon x64/Intel

Windows

x64/Intel/AMD ARM64

Možnost B: Sestavení ze zdrojového kódu

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

Nastavení databáze

Inicializujte schéma pgarachne vyžadované pro API tokeny.

psql -d my_database -f sql/schema.sql

Konfigurace

PgArachne načítá konfiguraci z proměnných prostředí nebo ze souboru.

Bezpečnostní poznámka: PgArachne nepracuje s hesly k databázi v konfiguračním souboru. Pro autentizaci spoléhá na standardní mechanismus PostgreSQL souboru .pgpass (nebo systémovou proměnnou PGPASSWORD).
Pořadí hledání: Pokud není konfigurační soubor specifikován přes CLI, hledá se v tomto pořadí:
  1. Aktuální složka: ./pgarachne.env (Všechny OS)
  2. Uživatelská konfigurace:
    • Linux / macOS: ~/.config/pgarachne/pgarachne.env
    • Windows: %USERPROFILE%\.config\pgarachne\pgarachne.env
  3. Systémová konfigurace: /etc/pgarachne/pgarachne.env (pouze Linux / macOS)
Proměnná Povinné Popis
Připojení k databázi
DB_HOST Ano Adresa PostgreSQL serveru (např. localhost).
DB_PORT Ne Port databáze. Výchozí: 5432.
DB_USER Ano Databázový uživatel, pod kterým se PgArachne připojuje.
HTTP Server
HTTP_PORT Ne Port pro naslouchání. Výchozí: 8080.
ALLOWED_ORIGINS Ne Nastavení CORS. Čárkou oddělený seznam povolených domén (např. https://mojeaplikace.cz). Výchozí: *.
STATIC_FILES_PATH Ne Absolutní cesta k servírování statických souborů (Explorer/Frontend).
Bezpečnost (JWT)
JWT_SECRET Ano Dlouhý náhodný řetězec používaný k podepisování relačních tokenů.
JWT_EXPIRY_HOURS Ne Platnost relace v hodinách. Výchozí: 8.
Logování
LOG_LEVEL Ne Úroveň detailů: DEBUG, INFO, WARN, ERROR. Výchozí: INFO.
LOG_OUTPUT Ne Kam zapisovat logy: stdout nebo cesta k souboru.

Průzkumník API (Explorer)

Explorer je webové rozhraní přiložené ve složce `tools/`. Nejedná se jen o dokumentaci; je to plně funkční demo aplikace postavená na HTML/JS, která komunikuje s databází výhradně prostřednictvím PgArachne.

Co umí?

  • Inspekce API: Čte funkci `capabilities` a zobrazuje všechny dostupné endpointy a jejich parametry.
  • Živé testování: Funkce můžete spouštět přímo z prohlížeče.
  • Automatická dokumentace: Vykresluje SQL komentáře (včetně metadat `--- PARAMS ---`) do čitelné dokumentace.
Jak jej povolit: Nastavte proměnnou prostředí `STATIC_FILES_PATH` tak, aby směřovala na složku `tools/pgarachne-explorer` na vašem disku. Poté navštivte http://localhost:8080.

Bezpečnost a autentizace

PgArachne se plně spoléhá na systém oprávnění PostgreSQL. Nevynalézá znovu Access Control Lists (ACL). Všechny dotazy jsou prováděny pod specifickou databázovou rolí ověřeného uživatele pomocí SET LOCAL ROLE.

1. Interaktivní přihlášení (JWT)

Uživatelé se autentizují pomocí svého skutečného PostgreSQL uživatelského jména a hesla přes přihlašovací funkci. Pokud je úspěšná, obdrží obecný JWT. Při použití tohoto tokenu přepne PgArachne aktivní roli na tohoto uživatele po dobu trvání požadavku.

2. Služby (API tokeny)

Pro automatizované systémy nebo skripty můžete použít dlouhodobé API klíče.

  • Tokeny jsou uloženy v tabulce pgarachne.api_tokens.
  • Každý token je mapován na konkrétního databázového uživatele/roli.
  • Token odešlete v hlavičce Authorization: Bearer <token>.

Kritická konfigurace: Oprávnění proxy

Jelikož se PgArachne připojuje jako uživatel definovaný v DB_USER (např. pgarachne) a přepíná identitu na jiné uživatele, proxy uživatel musí být členem těchto cílových rolí.

Spusťte toto SQL pro každého uživatele/roli, která se potřebuje přihlásit:

-- Povolit 'pgarachne' přepnout se na 'app_user'
GRANT app_user TO pgarachne;

Nasazení a HTTPS

PgArachne je navržen tak, aby dělal jednu věc dobře: API Gateway. Pro SSL/TLS (HTTPS), bezpečnost hlaviček a veřejné směrování byste před něj měli umístit Reverzní proxy.

Možnost A: Caddy Server

Nejlepší pro: Moderní produkční nasazení, snadné použití.

Caddy je jediný webový server, který ve výchozím nastavení automaticky získává a obnovuje SSL certifikáty (Let's Encrypt). Vyžaduje téměř nulovou konfiguraci.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Možnost B: Nginx

Nejlepší pro: Enterprise prostředí, komplexní směrování.

Nginx je průmyslovým standardem pro vysoce výkonné vyvažování zátěže (load balancing). Použijte jej, pokud již máte infrastrukturu Nginx. Certbot budete muset spravovat ručně.

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

Možnost C: Ngrok

Nejlepší pro: Lokální vývoj, dema, testování webhooků.

Ngrok vytváří bezpečný tunel z veřejného internetu přímo do vašeho notebooku bez konfigurace firewallu. Ideální pro okamžité ukázky kolegům. 

./ngrok http 8080

Chybové kódy

PgArachne vrací standardní chybové objekty JSON-RPC 2.0. Níže jsou uvedeny specifické kódy, se kterými se můžete setkat:

Kód Zpráva Význam
-32700 Parse error Server obdržel neplatný JSON.
-32601 Method not found Funkce ve schématu neexistuje.
-32602 Invalid params Argumenty neodpovídají signatuře funkce.
-32001 Permission denied Role aktuálního uživatele nemá oprávnění k provedení funkce (na úrovni DB).
-32000 Internal Error Obecná chyba serveru (zkontrolujte logy).

Podpořte vývoj

Vývoj open-source softwaru, jako je PgArachne, zabere značné množství času. Pokud vám tento nástroj šetří čas, zvažte, prosím, podporu jeho údržby.

☕ Staňte se členem

Připojte se ke komunitě na Buy Me a Coffee. Získejte exkluzivní aktualizace, dřívější přístup k novým funkcím a další.

Podpořit na Buy Me a Coffee

Bankovní převod

Přímá podpora s 0% poplatky.

🇺🇸 ACH (USA)
Jméno
Zbynek Vanzura
Číslo účtu
827908168786406
Typ účtu
Deposit
Směrovací číslo (Routing)
084009519
Swift/BIC
TRWIUS35XXX
Adresa banky
Wise US Inc, 108 W 13th St, Wilmington, DE, 19801, United States
🇪🇺 SEPA (Euro)
Jméno
Zbynek Vanzura
IBAN
BE68905813473834
Swift/BIC
TRWIBEB1XXX
Adresa banky
Wise, Rue du Trône 100, 3rd floor, Brussels, 1050, Belgium
🇨🇿 CZK (Česká rep.)
Jméno
Zbyněk Vanžura
Číslo účtu
2300354/2010

Kryptoměny

Podpora prostřednictvím digitálních aktiv.

Bitcoin (BTC)
BTC Adresa
bc1qw8swmnvk48lhcatyw55wz8g4gyjq3vkw0h78g6
USDT (TetherUS)
TRC20 Adresa
TPemgxu8jxkjyiHpqrUJyc3dNEs3aPSb2T
ERC20 Adresa
0xa689e1c6c8da09fcecca1b9733a22619f56288ff
Binance Pay
Darovat přes Binance Pay

Revolut

Nejrychlejší způsob, jak darovat. Podporuje Apple Pay, debetní či kreditní karty.

Darovat přes Revolut

PayPal

Snadné a bezpečné platby. Podporuje debetní či kreditní karty.

Wise

Snadné a bezpečné platby.

Licence a ochranná známka

Kód (MIT Licence):
Zdrojový kód můžete zdarma použít pro jakýkoli osobní nebo komerční projekt. Můžete jej upravovat, forkovat a šířit.

Značka (Ochranná známka):
Název "PgArachne" a Logo jsou ochranné známky Zbyňka Vanžury. Pokud projekt forknete nebo nabízíte komerční službu "Managed PgArachne", musíte odstranit původní branding a logo, pokud jste nezískali speciální licenci.

Copyright © 2025 Zbyněk Vanžura.