Ошибки и сообщения
Эта страница переведена при помощи нейросети GigaChat.
Вывод сообщений и ошибок
Команда RAISE предназначена для вывода сообщений и вызова ошибок.
RAISE [ level ] 'format' [, expression [, ... ]] [ USING option = expression [, ... ] ];
RAISE [ level ] condition_name [ USING option = expression [, ... ] ];
RAISE [ level ] SQLSTATE 'sqlstate' [ USING option = expression [, ... ] ];
RAISE [ level ] USING option = expression [, ... ];
RAISE ;
Параметр level задает важность ошибки. Допустимые уровни – это DEBUG, LOG, INFO, NOTICE, WARNING, и EXCEPTION, с EXCEPTION по умолчанию. EXCEPTION вызывает ошибку (которая обычно прерывает текущую транзакцию), другие уровни генерируют только сообщения различных уровней приоритета. Контроль того, будут ли сообщения определенного приоритета сообщены клиенту, записаны в журнал сервера или и то, и другое, осуществляется с помощью переменных конфигурации log_min_messages и client_min_messages. См. раздел «Конфигурация сервера» для получения дополнительной информации.
После level, если он есть, можно указать строку формата, которая должна быть простой строковой константой, а не выражением. Строка формата задает текст сообщения об ошибке, который будет сообщен. За строкой формата могут следовать необязательные выражения аргументов, которые будут вставлены в сообщение. Внутри строки формата % заменяется строковым представлением значения следующего необязательного аргумента. Напишите %%, чтобы выдать буквальный %. Количество аргументов должно соответствовать количеству заполнителей % в строке формата, иначе во время компиляции функции возникает ошибка.
В этом примере значение v_job_id заменит % в строке:
RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
Можно прикрепить дополнительную информацию к отчету об ошибке, написав USING, за которым следует option = expression элементы. Каждый expression может быть любым выражением со значением строки. Разрешенные ключевые слова option:
MESSAGE
Задает текст сообщения об ошибке. Этот параметр нельзя использовать в форме RAISE, включающей строку формата перед USING.
DETAIL
Предоставляет сообщение с подробностями об ошибке.
HINT
Предоставляет подсказку.
ERRCODE
Задает код ошибки (SQLSTATE), который необходимо сообщить, либо по имени условия, как показано в Приложении A, либо непосредственно как пятизначный код SQLSTATE.
COLUMNCONSTRAINTDATATYPETABLESCHEMA
Предоставляет имя связанного объекта.
Этот пример прервет транзакцию с указанным сообщением об ошибке и подсказкой:
RAISE EXCEPTION 'Nonexistent ID --> %', user_id
USING HINT = 'Please check your user ID';
Эти два примера показывают эквивалентные способы установки SQLSTATE:
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
Существует второй синтаксис , в котором основным аргументом является имя условия или SQLSTATE, которое должно быть сообщено, например:
RAISE division_by_zero;
RAISE SQLSTATE '22012';
В этом синтаксисе USING можно использовать для предоставления пользовательского сообщения об ошибке, детали или подсказки. Другой способ сделать предыдущий пример:
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
Еще один вариант – написать RAISE USING или RAISE level USING и поместить все остальное в список USING.
Последний вариант RAISE вообще не имеет параметров. Эта форма может использоваться только внутри блока BEGIN в предложении EXCEPTION. Это приводит к повторному выбросу ошибки, которая в данный момент обрабатывается.
До версии PostgreSQL 9.1, форма без параметров интерпретировалось как повторное выбрасывание ошибки из блока, содержащего активный обработчик исключений. Таким образом, предложение EXCEPTION, вложенное внутри этого обработчика, не могло его поймать, даже если RAISE находился внутри блока предложения EXCEPTION. Это было признано неожиданным, а также несовместимым с PL/SQL от Oracle.
Если в команде RAISE EXCEPTION не указано имя условия или SQLSTATE, используется значение по умолчанию raise_exception (P0001). Если текст сообщения не указан, по умолчанию используется имя условия или SQLSTATE в качестве текста сообщения.
При указании кода ошибки по коду SQLSTATE нет ограничения предопределенными кодами ошибок и можно выбрать любой код ошибки, состоящий из пяти цифр и/или заглавных букв ASCII, за исключением 00000. Рекомендуется избегать выбрасывания кодов ошибок, оканчивающихся тремя нулями, поскольку это коды категорий, которые могут быть перехвачены только путем перехвата всей категории.
Проверка утверждений
Оператор ASSERT является удобной сокращенной записью для вставки проверок отладки в функции PL/pgSQL.
ASSERT condition [ , message ];
condition – это логическое выражение, которое всегда должно оцениваться как истинное. Если оно таково, оператор ASSERT ничего не делает дальше. Если результат ложный или нулевой, то возникает исключение ASSERT_FAILURE. Если при оценке выражения condition происходит ошибка, она сообщается как обычная ошибка.
Если предоставляется необязательное утверждение message, то это выражение, результат которого (если он не равен нулю), заменяет стандартный текст сообщения об ошибке «утверждение не выполнено», если утверждение condition терпит неудачу. Выражение message не оценивается в обычном случае, когда утверждение успешно выполняется.
Тестирование утверждений может быть включено или отключено с помощью параметра конфигурации plpgsql.check_asserts, который принимает логическое значение. По умолчанию это on. Если этот параметр off, то операторы ASSERT ничего не делают.
Обратите внимание, что ASSERT предназначен для обнаружения ошибок программы, а не для сообщения об обычных ошибках. Используйте оператор RAISE, описанный выше, для этого.