Ошибки и сообщения

Вывод ошибок и сообщений

Для вывода расширенных сообщений и обработки ошибок используйте оператор RAISE.

RAISE [ уровень ] 'формат' [, выражение [, ... ]] [ USING параметр = выражение [, ... ] ];
RAISE [ уровень ] имя_условия [ USING параметр = выражение [, ... ] ];
RAISE [ уровень ] SQLSTATE 'код_ошибки' [ USING параметр = выражение [, ... ] ];
RAISE [ уровень ] USING параметр = выражение [, ... ];
RAISE ;

В параметре уровень задается серьезность ошибки. Допустимые уровни: DEBUG, LOG, INFO, NOTICE, WARNING и EXCEPTION (уровень по умолчанию). EXCEPTION вызывает ошибку (которая обычно прерывает текущую транзакцию); другие уровни просто генерируют сообщения с различными уровнями приоритета. Будут ли сообщения определенного приоритета передаваться клиенту, записываться в журнал сервера или делать и то, и другое, зависит от переменных конфигурации log_min_messages и client_min_messages. Дополнительную информацию см. в главе Конфигурация сервера.

После уровня, если он имеется, можно задать строку формата (который должен быть простым строковым литералом, а не выражением). Строка формата определяет текст выводимого сообщения об ошибке. За строкой формата могут идти необязательные выражения аргументов, которые будут вставлены в сообщение. Внутри строки формата % заменяется строковым представлением значения следующего необязательного аргумента. Чтобы получить буквальный знак %, напишите %%. Количество аргументов должно соответствовать количеству местозаполнителей % в строке формата, иначе при компиляции функции возникает ошибка.

В этом примере знак % в строке будет заменен на значение v_job_id:

RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
           -- Вызов функции cs_create_job(%)

Написав USING, а затем элементы параметр = выражение, можно прикрепить к отчету об ошибке дополнительную информацию. Каждое выражение может быть любым строковым выражением. Допустимые ключевые слова параметра:

MESSAGE
Устанавливает текст сообщения об ошибке. Этот параметр нельзя использовать в форме RAISE, включающей строку формата перед USING.

DETAIL
Предоставляет подробное сообщение об ошибке.

HINT
Предоставляет подсказку.

ERRCODE
Задает выводимый код ошибки (SQLSTATE) либо по имени условия, как показано в главе Коды ошибок QHB, либо непосредственно в виде пятизначного кода SQLSTATE.

COLUMN
CONSTRAINT
DATATYPE
TABLE
SCHEMA
Предоставляют имя объекта, связанного с ошибкой.

Этот пример прервет транзакцию с заданным сообщением об ошибке и подсказкой:

RAISE EXCEPTION 'Nonexistent ID --> %', user_id
              -- Несуществующий ID --> %
      USING HINT = 'Please check your user ID';
                 -- Пожалуйста, проверьте ваш пользовательский ID

Эти два примера показывают равнозначные способы установки SQLSTATE:

RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
-- Дубликат идентификатора пользователя

Существует второй синтаксис RAISE, в котором основным аргументом является имя условия или выводимый SQLSTATE, например:

RAISE division_by_zero;
RAISE SQLSTATE '22012';

В этом синтаксисе для предоставления пользователю сообщения об ошибке, детализации или подсказки можно использовать USING. Другой способ выполнить предыдущий пример:

RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;

Еще один вариант — написать RAISE USING или RAISE уровень USING и поместить все остальное в список USING.

Последний вариант RAISE вообще не имеет параметров. Эту форму можно использовать только внутри предложения EXCEPTION блока BEGIN; с ее помощью ошибка, обрабатываемая в данный момент, вызывается повторно.

Если в команде RAISE EXCEPTION не указаны ни имя условия, ни SQLSTATE, по умолчанию используется raise_exception (P0001). Если не задан текст сообщения, по умолчанию в качестве текста сообщения используется имя условия или SQLSTATE.

Примечание
При указании кода ошибки с помощью кода SQLSTATE вы не ограничены предопределенными кодами. Можно выбрать любой код ошибки, состоящий из пяти цифр и/или букв ASCII в верхнем регистре, кроме 00000. Не рекомендуется использовать коды ошибок, заканчивающиеся тремя нулями, потому что это коды категорий, которые можно перехватить, только перехватив всю категорию.

Проверка утверждений

Оператор ASSERT представляет собой удобное сокращение для вставки отладочных проверок в функции PL/pgSQL.

ASSERT условие [, сообщение ];

условие является логическим выражением, которое, как ожидается, всегда вычисляется как true; если это так, оператор ASSERT больше ничего не делает. При результате false или NULL выдается исключение ASSERT_FAILURE. (Если ошибка возникает при вычислении условия, она выводится как обычная ошибка.)

Если предоставляется необязательное сообщение, то результат этого выражения (если это не NULL) заменяет стандартный текст сообщения об ошибке «assertion failed» (утверждение не выполнено), если условие выдает ошибку. В обычном случае, когда утверждение успешно выполняется, выражение сообщения не вычисляется.

Тестирование утверждений можно включить или выключить с помощью параметра конфигурации plpgsql.check_asserts, который принимает логическое значение; значение по умолчанию on (включен). Если этот параметр равен off (выключен), то операторы ASSERT ничего не делают.

Обратите внимание, что ASSERT предназначен для обнаружения программных ошибок, а не для сообщения об обычных ошибках. Для них следует использовать описанный выше оператор RAISE.