Kategoria: Supabase i bazy danych

Supabase — duplikaty rekordów po ponownieniu webhooka: różnicowa diagnostyka i test naprawy

Poradnik techniczny · Kacper Bernecki

Problem: po ponownieniu webhooka (np. z zewnętrznego systemu lub z mechanizmu retry w platformie) w tabeli pojawiają się duplikaty rekordów. Typowy mechanizm: zewnętrzny serwis wysyła żądanie POST do funkcji HTTP/Edge Function lub bezpośrednio do REST API Supabase, a przy braku jasnej idempotencji serwis powtarza żądanie — tworzone są kopie wpisów. W tym dokumencie pokazuję jak odróżnić duplikaty wynikające z braku ograniczeń w bazie od duplikatów z powodu aplikacyjnych wyścigów (race) lub błędnego potwierdzania przyjmowania webhooka. Zawieram sprawdzone testy lokalne i w środowisku produkcyjnym oraz kroki naprawcze, które nie wymagają wymyślonych narzędzi ani dostępu do prywatnych danych.

Jak rozpoznać przyczynę

Sprawdź, czy tabela ma constraint UNIQUE lub PRIMARY KEY na polach, które powinny być unikalne: brak takiego ograniczenia to najczęstsza przyczyna. Zapytanie: SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint WHERE conrelid = 'schema.table'::regclass; jeśli brak ograniczenia, każdy retry utworzy nowy wiersz.

Przeanalizuj logi przyjmujące webhooki: czy serwis odpowiada HTTP 2xx przed zapisaniem? Jeśli odpowiedź 200 jest wysyłana natychmiast, a zapis odbywa się asynchronicznie, nadawca może uznać żądanie za dostarczone i nie zareagować na późniejszy błąd, lub odwrotnie — powtórzyć jeśli status nie 2xx. Zbadaj timestampy i body żądań w logach serwera.

Zidentyfikuj wyścigi (race conditions): przy równoległych żądaniach bez atomowych operacji upsert INSERT ... ON CONFLICT dojdzie do duplikatów. Sprawdź czy aplikacja używa INSERT z ON CONFLICT DO NOTHING/UPDATE lub transakcji z blokadami SELECT ... FOR UPDATE, oraz czy generowane są kolizje kluczy naturalnych vs surrogate.

Rozwiązanie krok po kroku

1. Utwórz kopię problematycznej tabeli w środowisku testowym (pg_dump/restore) i odtwórz scenariusz wysyłając ponawiające się żądania z tymi samymi danymi, aby powtórzyć problem bez ryzyka dla produkcji.

2. Dodaj unikalny constraint na kombinację pól identyfikujących logicznie rekordy (np. external_id, type, date). Użyj ALTER TABLE ... ADD CONSTRAINT ... UNIQUE i sprawdź błędy lub konflikty przy ponownym żądaniu.

3. Zmień inserty na upserty: testuj INSERT ... ON CONFLICT (external_id) DO UPDATE SET updated_at = EXCLUDED.updated_at; jeśli logika wymaga, zaktualizuj pola zamiast tworzyć nowe wiersze.

4. Wprowadź idempotency key: przyjmij z nagłówka webhooka unikalny idempotency-key i zapisuj go w osobnej tabeli lub kolumnie. Przed wstawieniem sprawdź, czy klucz już istnieje — jeśli tak, zwróć 200 bez duplikowania.

5. Przetestuj obsługę odpowiedzi HTTP: symuluj opóźnienia i błędy zapisu, upewnij się, że serwis webhook zwraca 4xx/5xx zgodnie z faktem niepowodzenia zapisu, a nie 2xx. Zaimplementuj retry policy po stronie klienta z wykrywaniem idempotency key.

6. Jeśli używasz Supabase Edge Function, dodaj atomową transakcję SQL wewnątrz funkcji lub wykorzystaj RPC (stored procedure) z zabezpieczeniem unique constraint, aby operacja była jednoetapowa i deterministyczna.

Jak sprawdzić, czy problem zniknął

Wyślij sekwencję identycznych żądań webhook z tym samym external_id i idempotency-key; po zastosowaniu upsert/unique constraint liczba rekordów powinna pozostać 1, a zwrócona odpowiedź 200 powinna być deterministyczna.

Wygeneruj równoległe żądania (np. 10 równych POST) z krótkimi opóźnieniami i potwierdź w logach bazy, że operacje są rozwiązywane jako konflikt ON CONFLICT lub odrzucone przez UNIQUE; liczba powodzeń insertów powinna wynosić 1.

Sprawdź logi konsumenta webhooków: przy idempotency-key ponowienia powinny rejestrować zwrot 200 bez zmian w tabeli; przy braku key sprawdź, że powtórzenia zwracają błąd lub są obsługiwane bez tworzenia duplikatu.

Czego nie robić

Nie polegaj wyłącznie na aplikacyjnym sprawdzeniu istnienia rekordu przed INSERT; w środowisku równoległym to prowadzi do race condition. Użyj constraint i ON CONFLICT w bazie.

Nie traktuj 200 jako dowodu trwałego zapisu. Pewne systemy potwierdzają przyjęcie do kolejki. Weryfikuj zapis w DB zanim zwrócisz sukces, lub użyj idempotency-key.