Procedury składowane w PostgreSQL/Język PLpgSQL/Komunikaty i błędy

Dodaj linki
Z Wikibooks, biblioteki wolnych podręczników.

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:

  1. 5-znakowy kod (ang. state),
  2. treść komunikatu (ang. message),
  3. szczegóły, np. fragment zapytania w którym występuje błąd składniowy (ang. detail),
  4. 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[edytuj]

Instrukcja 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.

Źródło: „https://pl.wikibooks.org/w/index.php?title=Procedury_składowane_w_PostgreSQL/Język_PLpgSQL/Komunikaty_i_błędy&oldid=399169”