Procedury składowane w PostgreSQL/Język PLpgSQL/Komunikaty i błędy
W PL/pgSQL istnieje specjalna instrukcja RAISE, która pozwala zgłaszać komunikaty o różnym poziomie ważności:
- informacje diagnostyczne (debug),
- informacje (ang. notice),
- ostrzeżenia (ang. warning),
- wyjątki (exceptions),
- poważne błędy (fatal, panic).
W zależności od ważności i ustawień serwera komunikaty mogą być logowane, co pomaga m.in. debuggować procedury; np. parametr log_min_message decyduje, od jakiego poziomu ważności są wykonywane zapisy (domyślnie notice).
Komunikaty w PostgreSQL mogą zostać zgłoszone przez serwer, np. z powodu naruszenia ograniczeń przy zmianie danych, braku pamięci itp., lub też zgłoszone z poziomu procedury składowanej. Identyfikuje je nazwa symboliczna, pisana małymi literami, albo równoważny 5-znakowy kod. Lista nazw i kodów jest dostępna w dodatku A dokumentacji.
Komunikat zawiera następujące informacje:
- 5-znakowy kod (ang. state),
- treść komunikatu (ang. message),
- szczegóły, np. fragment zapytania w którym występuje błąd składniowy (ang. detail),
- podpowiedź, co można zrobić, żeby uniknąć błędu (ang. hint).
Zależnie od charakteru błędu nie wszystkie te dane muszą wystąpić. Na pewno zawsze będzie dostępny kod, bardzo często treść, rzadziej podpowiedź.
W PL/pgSQL zgłaszając błędy można ustawić wszystkie parametry. Przy łapaniu wyjątków dostęp jest jedynie do nazwy albo kodu, zależnie od zapisu w kodzie źródłowym; ma się to zmienić w wersji 9.2, gdzie rozszerzone polecenie GET STACKED DIAGNOSTICS pozwoli odczytać wszystkie parametry.
Składnia
edytujInstrukcja RAISE występuje w kilku wariantach:
- RAISE nazwa wyjątku
- Zgłaszany jest wyjątek o podanej nazwie.
- Np. RAISE unique_violation.
- RAISE SQLSTATE '5-znakowy numer wyjątku'
- Zgłaszany jest wyjątek o podanym kodzie; w takim przypadku kod może być dowolny (oprócz 00000), nie musi odpowiadać żadnemu predefiniowanemu.
- Np. RAISE SQLSTATE '23505' (tutaj 23505 = unique_violation).
- RAISE 'wzorzec komunikatu' [ , lista wyrażeń ]
- Zgłaszany jest wyjątek o kodzie P0001 (raise_exception) i komunikacie sformatowanym na podstawie wzorca. Specjalnym znakiem we wzorcu jest znak procenta ('%'), który zastępują kolejne elementy z listy wyrażeń, skonwertowane na napisy; '%%' wprowadza do napisu znak procenta.
- Np. RAISE 'x=%, y=%, wsp=% %%', x, y, wsp; da komunikat postaci "x=12, y=50, wsp=1.25 %".
- RAISE USING lista parametr = napis, parametr = napis, ...
- Parametrem mogą być następujące literały: MESSAGE, DETAIL, HINT, ERRCODE. Np.
RAISE USING
MESSAGE = 'Treść komunikatu',
DETAIL = 'Szczegóły',
HINT = 'Podpowiedź',
ERRCODE = 'nazwa_wyjątku' -- pisana małymi literami!
;
Formalnie składnia instrukcji RAISE jest następująca:
RAISE [ poziom ] 'wzorzec' [, wyrażenie [, ... ]] [ USING parametr = wyrażenie [, ... ] ]; RAISE [ poziom ] nazwa_wyjątku [ USING parametr = wyrażenie [, ... ] ]; RAISE [ poziom ] SQLSTATE 'kod wyjątku' [ USING parametr = wyrażenie [, ... ] ]; RAISE [ poziom ] USING parametr = wyrażenie [, ... ];
Poziom jest jednym z literałów:
- DEBUG - informacja diagnostyczna (zwykle zapisywana w logach),
- NOTICE - informacja,
- WARNING - ostrzeżenie,
- EXCEPTION - wyjątek,
- FATAL, PANIC - w skrócie katastrofa.
Jeśli poziom nie jest podany przyjmuje domyślną wartość EXCEPTION.
Jeśli występuje wzorzec, to w klauzuli USING nie może wystąpić parametr MESSAGE.