Ошибки и сообщения
Эта страница переведена при помощи нейросети 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 (если таковой имеется) укажите строку format (которая должна быть простым строковым литералом, а не выражением). Строка формата задает текст сообщения об ошибке, которое необходимо вывести. За строкой формата могут следовать выражения необязательных аргументов, которые будут вставлены в сообщение. Внутри строки формата символ % заменяется строковым представлением значения следующего необязательного аргумента. Напишите %% для вывода литерала %. Количество аргументов должно совпадать с количеством символов % в строке формата, иначе во время компиляции функции будет выдана ошибка.
В этом примере значение v_job_id заменит символ % в строке:
RAISE NOTICE 'Calling cs_create_job(%)', v_job_id;
Во втором и третьем вариантах синтаксиса condition_name и sqlstate указывают имя условия ошибки или пятисимвольный код SQLSTATE соответственно.
Вот примеры использования condition_name и sqlstate:
RAISE division_by_zero;
RAISE WARNING SQLSTATE '22012';
Можно прикрепить дополнительную информацию к отчету об ошибке, написав USING, за которым следует option = expression элементы. Каждый expression может быть любым выражением со значением строки. Разрешенные ключевые слова option:
MESSAGE
Задает текст сообщения об ошибке. Этот параметр нельзя использовать в первом варианте синтаксиса, поскольку сообщение уже предоставлено.
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';
Другой способ получить тот же результат:
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, описанный выше, для этого.