O projekcie i architekturze

2 min czytania

O projekcie i architekturze

PgArachne™ działa jako lekki, wysokowydajny serwer WWW, który stoi między Twoimi klientami HTTP a bazą danych PostgreSQL. Eliminuje potrzebę korzystania z tradycyjnych języków backendowych (takich jak Python, Node.js czy PHP), mapując żądania HTTP bezpośrednio na funkcje bazy danych.

Kluczowe możliwości techniczne

  • Brama JSON-RPC 2.0: Wszystkie interakcje z API są zgodne ze ścisłą specyfikacją JSON-RPC 2.0. Nie ma potrzeby projektowania endpointów REST; wystarczy wywoływać funkcje SQL po nazwie za pomocą żądań POST.
  • Natywna autoryzacja bazodanowa: Żadnych osobnych tabel użytkowników. Użytkownicy logują się za pomocą swoich rzeczywistych danych uwierzytelniających PostgreSQL, aby otrzymać JWT. Alternatywnie konta usługowe mogą korzystać z trwałych tokenów API.
  • Maskowanie ról (Role Masquerading): PgArachne™ łączy się jako użytkownik proxy, ale każde żądanie wykonuje za pomocą SET LOCAL ROLE, przełączając się na tożsamość uwierzytelnionego użytkownika. Row-Level Security (RLS) działa automatycznie.
  • MCP (Model Context Protocol): Natywny endpoint MCP pozwala klientom AI, takim jak Claude Desktop, Cursor i innym narzędziom kompatybilnym z MCP, odkrywać Twoje funkcje PostgreSQL jako narzędzia i wywoływać je bezpośrednio — bez konieczności pisania niestandardowego kodu łączącego. Obowiązuje ta sama autoryzacja i to samo bezpieczeństwo ról. Zasoby (tabele/widoki) oraz szablony promptów są również udostępniane przez MCP.
  • Powiadomienia w czasie rzeczywistym (SSE): Subskrybuj kanały PostgreSQL NOTIFY przez SSE, aby uzyskać aktualizacje na żywo bez pollingu.
  • Serwer plików statycznych: PgArachne™ może serwować statyczne zasoby (HTML, JS, CSS), umożliwiając hostowanie Single Page Applications (SPA) lub narzędzia Explorer bezpośrednio.

Ta architektura znacząco upraszcza stack: Baza danych ↔ PgArachne ↔ Frontend/agent AI.

Struktura endpointów: Wszystkie endpointy bazodanowe współdzielą wspólny prefiks (domyślnie db, konfigurowalny za pomocą API_PREFIX):
POST /{prefix}/{database}/jsonrpc — brama JSON-RPC 2.0
GET  /{prefix}/{database}/sse    — strumień PostgreSQL NOTIFY
POST /{prefix}/{database}/mcp   — Model Context Protocol

Zobacz szczegółowe decyzje architektoniczne