PostgREST – w pełni funkcjonalne RESTful API dla PostgreSQL

Błyskawiczne API bezpośrednio z Twojej bazy danych

Współczesny cykl tworzenia oprogramowania często wymaga pisania setek linijek powtarzalnego kodu (boilerplate) po stronie backendu, tylko po to, aby obsłużyć podstawowe operacje CRUD. A co gdyby ten etap można było całkowicie pominąć i oprzeć logikę wyłącznie na sprawdzonym silniku bazy danych? Z pomocą przychodzi PostgREST.

Do czego służy ten projekt?

PostgREST to niezależny, niezwykle wydajny serwer webowy (napisany w języku Haskell), który automatycznie generuje gotowe, w pełni funkcjonalne API RESTful bezpośrednio ze schematu bazy PostgreSQL.

Zamiast pisać własną aplikację pośredniczącą (np. w Node.js, Pythonie czy Javie), projektujesz strukturę bazy – tabele, widoki, funkcje czy relacje. PostgREST w czasie rzeczywistym analizuje ten schemat i udostępnia go jako endpointy HTTP. Przykładowo, stworzenie tabeli users natychmiast daje dostęp do endpointu /users z obsługą metod GET, POST, PATCH i DELETE.

Główne zalety takiego rozwiązania:

  • Brak zbędnego kodu: Pozwala zrezygnować z pisania pośredniego kodu backendowego.
  • Maksymalna wydajność: Eliminuje problem tworzenia setek obiektów w pamięci przez systemy ORM, zamieniając żądania HTTP prosto w zoptymalizowany kod SQL.
  • Jedno źródło prawdy: Zarówno struktura danych, jak i logika biznesowa oraz zabezpieczenia znajdują się w jednym miejscu – w bazie danych.

Autoryzacja w PostgREST

System autoryzacji w PostgREST to prawdziwy pokaz możliwości nowoczesnego PostgreSQL. Narzędzie to nie posiada własnego systemu logowania, nie przechowuje haseł ani nie generuje tokenów. Zamiast tego całkowicie polega na mechanizmach wbudowanych w bazę danych, łącząc je ze standardem JWT (JSON Web Tokens).

Jak to działa w praktyce?

  1. Weryfikacja tokenu: Klient przesyła token JWT w nagłówku HTTP. PostgREST weryfikuje jego podpis kryptograficzny za pomocą zdefiniowanego wcześniej klucza.
  2. Przełączenie roli (Impersonation): Z tokenu odczytywana jest rola użytkownika (np. admin, autor, czytelnik). Przed wykonaniem jakiegokolwiek zapytania, PostgREST instruuje bazę, aby przełączyła się na tę konkretną rolę (za pomocą polecenia SET ROLE).
  3. Row-Level Security (RLS): Całe bezpieczeństwo opiera się na natywnej funkcjonalności RLS w PostgreSQL. W bazie piszesz zasady polityki dostępu (polices), np. definiując, że użytkownik z rolą autor może modyfikować wyłącznie te rekordy, których author_id zgadza się z jego identyfikatorem przekazanym w tokenie JWT.

Dzięki temu zabezpieczasz dane na najniższym, najpewniejszym poziomie, a API staje się jedynie szybką bramką transmisyjną.

Instalacja za pomocą Docker Compose

PostgREST to pojedynczy, bezstanowy plik binarny, co czyni go idealnym kandydatem do konteneryzacji. Poniżej znajduje się krótki i gotowy do użycia plik docker-compose.yml, który podniesie zarówno bazę PostgreSQL, jak i przypięte do niej API:

services:
  db:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: Twoje_haslo123
      POSTGRES_DB: app_db
    ports:
      - "5432:5432"

  api:
    image: postgrest/postgrest:latest
    restart: always
    environment:
      # Połączenie z naszą bazą danych zdefiniowaną wyżej
      PGRST_DB_URI: postgres://admin:Twoje_haslo123@db:5432/app_db
      # Schemat bazy, z którego generowane jest API
      PGRST_DB_SCHEMA: public
      # Domyślna rola dla zapytań bez tokenu JWT
      PGRST_DB_ANON_ROLE: anonimowy
      # Klucz do weryfikacji tokenów JWT (min. 32 znaki)
      PGRST_JWT_SECRET: super_tajny_klucz_do_podpisywania_jwt_32_znaki
    ports:
      - "3000:3000"
    depends_on:
      - db

Wystarczy uruchomić komendę docker compose up -d, a Twoje API będzie dostępne pod adresem http://localhost:3000. Aby wszystko działało poprawnie, należy jedynie pamiętać o utworzeniu roli anonimowy bezpośrednio w bazie PostgreSQL.

Aby dowiedzieć się więcej i zgłębić techniczne detale, warto zajrzeć do oficjalnych źródeł: