Nowość w Endora Commerce: wbudowany CRM z szansami sprzedażowymi Zobacz →
Endora Commerce

Integracja z PostgreSQL

PostgreSQL to baza danych stojąca za Endora Commerce: katalog, zamówienia, ceny, organizacje i cała reszta danych mieszka w standardowej instalacji, którą możesz hostować u siebie. Poniżej to, co warto wiedzieć, zanim postawisz ją na produkcji.

Jedna baza jako system rekordu

PostgreSQL to otwartoźródłowa relacyjna baza danych rozwijana przez społeczność, z korzeniami w projekcie POSTGRES na Uniwersytecie Kalifornijskim w Berkeley. W Endora Commerce nie jest opcją do wyboru spośród kilku silników, tylko jedyną bazą, na której platforma działa.

Każda część platformy, która potrzebuje systemu rekordu (silnik cen, cykl życia zamówienia, zapytania ofertowe, hierarchia organizacji, dziennik audytu), czyta i zapisuje do tej samej bazy. Nie ma osobnego, własnościowego magazynu danych dla żadnej z tych rzeczy. Backend sięga do niej przez Fastify z MikroORM, a kontrakty Zod sprawdzają typy po obu stronach każdego żądania.

Pozostałe elementy stosu trzymają wyłącznie dane pochodne albo robocze:

SystemCo trzymaCo się dzieje, gdy zniknie
PostgreSQLWszystkie dane źródłowePlatforma nie działa, potrzebne jest odtworzenie z kopii
RedisCache i kolejki zadańNic nie ginie z danych źródłowych, zadania w kolejce się opóźniają
MeilisearchIndeks wyszukiwania kataloguListing produktów jest serwowany z PostgreSQL, a indeks każdego kanału da się odbudować z bazy jednym poleceniem

W praktyce oznacza to, że plan kopii zapasowych i odtwarzania dotyczy przede wszystkim tej jednej bazy.

Czego potrzebujesz po stronie bazy

  • Wersja. Wymagany jest PostgreSQL 16.x. Z tej samej wersji korzystają środowisko deweloperskie i referencyjny plik Compose dla produkcji. Według polityki wersjonowania PostgreSQL każda wersja główna jest wspierana przez pięć lat, a wersja 16 do listopada 2028 r.
  • Połączenie. Backend dostaje adres bazy w jednej zmiennej środowiskowej, DATABASE_URL. Zawiera ona hasło, więc traktuj ją jak sekret. Możesz hostować bazę sam, oddać ją partnerowi albo skorzystać z usługi zarządzanego PostgreSQL: zmienia się tylko connection string.
  • Rozszerzenie pg_trgm. Jedna z migracji modułu feedów produktowych tworzy rozszerzenie pg_trgm, używane do podpowiedzi przy wyszukiwaniu kategorii w taksonomii. To standardowy moduł PostgreSQL oznaczony jako zaufany, czyli może go zainstalować użytkownik z uprawnieniem CREATE w danej bazie. Przy bazie zarządzanej sprawdź przed migracją, czy dostawca udostępnia to rozszerzenie.
  • Sieć. W referencyjnym wdrożeniu baza działa w wewnętrznej sieci kontenerów i nie jest wystawiona na zewnątrz. Sięgają do niej tylko procesy backendu.

Migracje i aktualizacje

Schemat nie jest zakładany ręcznie. Każdy moduł ma własne pliki migracji, a platforma wykonuje je moduł po module, w kolejności wynikającej z zależności między modułami. Cały przebieg odbywa się w jednej transakcji: albo przechodzą wszystkie migracje, albo żadna.

W referencyjnym wdrożeniu kolejność startu jest stała: baza zgłasza gotowość, osobny jednorazowy krok uruchamia migracje, kolejny instaluje moduły i dopiero potem startuje API oraz sklep.

Migracje nie działają wstecz. Dlatego dokumentacja aktualizacji każe przed podniesieniem wersji zrobić kopię bazy i zatrzymać API razem z procesami obsługującymi kolejki, żeby nic nie obsługiwało żądań w trakcie zmiany schematu.

Kopie zapasowe i monitoring

Ponieważ to zwykły PostgreSQL, a nie własnościowy fork, standardowe narzędzia do backupu, monitoringu, replikacji i hostingu działają bez modyfikacji. Dokumentacja wdrożeniowa zaleca minimum, które warto mieć od pierwszego dnia:

  1. Cykliczny zrzut pg_dump uruchamiany z crona i odkładany poza serwer, na którym stoi baza.
  2. Kopię plików razem z bazą. Zdjęcia produktów i pliki PDF faktur nie leżą w PostgreSQL, tylko w magazynie plików: na dysku serwera albo w Amazon S3 lub Google Cloud Storage. Odtworzona baza bez plików to katalog z niedziałającymi obrazkami.
  3. Próbne odtworzenie obu kopii w osobnym środowisku jeszcze przed startem produkcyjnym.

Do monitoringu służy endpoint GET /api/v1/_health. Wykonuje proste zapytanie do bazy, sprawdza też Redis i Meilisearch, a gdy któraś z zależności jest nieosiągalna, odpowiada kodem 503. Można go podpiąć pod load balancer albo zewnętrzny monitoring.

O czym pamiętać przy bezpośrednim dostępie do bazy

Izolacja danych między organizacjami kupujących jest wymuszana w warstwie dostępu do danych w backendzie, a nie przez osobne bazy dla każdego klienta. Konto bazodanowe podłączone bezpośrednio, na przykład z narzędzia raportowego, działa poza tym mechanizmem i widzi dane wszystkich organizacji. Takim kontom warto dawać dostęp tylko do odczytu, a integracje zapisujące dane prowadzić przez API platformy, nie przez SQL.

Sprawdźmy, co da się podłączyć u Ciebie

Umów bezpłatną konsultację. Przejdziemy przez Twój ERP, magazyn i procesy sprzedaży, i pokażemy, jak wygląda ścieżka integracji krok po kroku.

Michał Zabielski, założyciel i CEO Endory

Michał Zabielski

Założyciel i CEO Endory

Odpowiadamy w ciągu jednego dnia roboczego.