40.9. Ошибки и сообщения#
40.9. Ошибки и сообщения #
40.9.1. Сообщения об ошибках и сообщения #
Используйте оператор RAISE
для вывода сообщений и генерации ошибок.
RAISE [level
] 'format
' [,expression
[, ... ]] [USINGoption
=expression
[, ... ]]; RAISE [level
]condition_name
[USINGoption
=expression
[, ... ]]; RAISE [level
] SQLSTATE 'sqlstate
' [USINGoption
=expression
[, ... ]]; RAISE [level
] USINGoption
=expression
[, ... ]; RAISE ;
Опция level
определяет уровень серьезности ошибки. Допустимые уровни: DEBUG
, LOG
, INFO
, NOTICE
, WARNING
и EXCEPTION
, по умолчанию используется EXCEPTION
. Уровень EXCEPTION
вызывает ошибку (что обычно приводит к прерыванию текущей транзакции), а остальные уровни только генерируют сообщения различных приоритетов. Отображение сообщений определенного приоритета для клиента, запись в журнал сервера или и то, и другое контролируется переменными конфигурации log_min_messages и client_min_messages. Дополнительную информацию см. в разделе Глава 18.
После level
, если такой параметр есть, вы можете указать строку формата format
(которая должна быть простым строковым литералом, а не выражением). Строка формата определяет текст сообщения об ошибке, который будет отображаться. За строкой формата может следовать необязательные выражения аргументов, которые будут вставлены в сообщение. Внутри строки формата символ %
заменяется на строковое представление значения следующего необязательного аргумента. Для вывода литерала %
используйте %%
. Количество аргументов должно соответствовать количеству заполнителей %
в строке формата, иначе при компиляции функции будет вызвана ошибка.
В этом примере значение 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.
COLUMN
CONSTRAINT
DATATYPE
TABLE
SCHEMA
#Предоставляет имя связанного объекта.
Этот пример прерывает транзакцию с заданным сообщением об ошибке и подсказкой:
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
, в котором основным аргументом является имя условия или SQLSTATE, которое должно быть сообщено, например:
RAISE division_by_zero; RAISE SQLSTATE '22012';
В этом синтаксисе USING
может использоваться для предоставления пользовательского сообщения об ошибке, детали или подсказки. Другой способ выполнить предыдущий пример
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
Одним из вариантов является написание RAISE USING
или RAISE
и помещение
всего остального в список уровень
USINGUSING
.
Последний вариант команды RAISE
не имеет параметров вообще.
Эта форма может использоваться только внутри
предложения EXCEPTION
блока BEGIN
;
она вызывает повторное возбуждение обрабатываемой в данный момент ошибки.
Примечание
До версии PostgreSQL 9.1, команда RAISE
без параметров интерпретировалась как повторное возбуждение ошибки из блока, содержащего активный обработчик исключений. Таким образом, вложенная в этот обработчик EXCEPTION
не могла ее перехватить, даже если команда RAISE
находилась в блоке вложенной EXCEPTION
. Это было считано неожиданным и несовместимым с PL/SQL Oracle.
Если ни имя условия, ни SQLSTATE не указаны в команде
RAISE EXCEPTION
, по умолчанию используется
raise_exception
(P0001
).
Если текст сообщения не указан, по умолчанию используется имя условия
или SQLSTATE в качестве текста сообщения.
Примечание
При указании кода ошибки по коду SQLSTATE вы не ограничены предопределенными кодами ошибок, но можете выбрать любой код ошибки, состоящий из пяти цифр и/или заглавных букв ASCII, кроме 00000
. Рекомендуется избегать выбрасывания кодов ошибок, оканчивающихся на три нуля, поскольку они являются кодами категорий и могут быть перехвачены только путем перехвата всей категории.
40.9.2. Проверка утверждений #
ASSERT
- это удобное сокращение для вставки отладочных проверок в функции PL/pgSQL.
ASSERTcondition
[ ,message
];
condition
- это логическое выражение,
которое ожидается всегда true; если это так,
оператор ASSERT
не выполняет никаких дополнительных действий.
Если результат ложный или null, то возникает исключение ASSERT_FAILURE
.
(Если происходит ошибка при вычислении условия condition
,
она сообщается как обычная ошибка).
Если предоставлен необязательный параметр message
, то это выражение, результат которого (если не является пустым) заменяет текст сообщения об ошибке по умолчанию “assertion failed”, если condition
не выполняется.
Выражение message
не вычисляется в обычном случае, когда утверждение выполняется успешно.
Все проверки утверждений могут быть включены или отключены с помощью параметра конфигурации plpgsql.check_asserts
, который принимает значение типа Boolean; значение по умолчанию - on
. Если этот параметр установлен в значение off
, то операторы ASSERT
не выполняют никаких действий.
Обратите внимание, что ASSERT
предназначен для обнаружения ошибок в программе, а не для сообщения об обычных условиях ошибок. Для этого используйте оператор RAISE
, описанный выше.