41.9. Сообщения и ошибки #
41.9.1. Вывод сообщений и ошибок #
Команда RAISE
предназначена для вывода сообщений и вызова ошибок.
RAISE [уровень
] 'формат
' [,выражение
[, ... ]] [ USINGпараметр
=значение
[, ... ] ]; RAISE [уровень
]имя_условия
[ USINGпараметр
=выражение
[, ... ] ]; RAISE [уровень
] SQLSTATE 'sqlstate
' [ USINGпараметр
=выражение
[, ... ] ]; RAISE [уровень
] USINGпараметр
=выражение
[, ... ]; RAISE ;
уровень
задаёт уровень важности ошибки. Возможные значения: DEBUG
, LOG
, INFO
, NOTICE
, WARNING
и EXCEPTION
. По умолчанию используется EXCEPTION
. EXCEPTION
вызывает ошибку (что обычно прерывает текущую транзакцию), остальные значения уровня
только генерируют сообщения с различными уровнями приоритета. Будут ли сообщения конкретного приоритета переданы клиенту или записаны в журнал сервера, или и то, и другое, зависит от конфигурационных переменных log_min_messages и client_min_messages. За дополнительными сведениями обратитесь к Главе 18.
После указания уровня
, если оно есть, можно задать строку формата
(это должна быть простая строковая константа, не выражение). Строка формата определяет вид текста об ошибке, который будет выдан. За строкой формата могут следовать необязательные выражения аргументов, которые будут вставлены в сообщение. Внутри строки формата знак %
заменяется строковым представлением значения очередного аргумента. Чтобы выдать символ %
буквально, продублируйте его (как %%
). Число аргументов должно совпадать с числом местозаполнителей %
в строке формата, иначе при компиляции функции возникнет ошибка.
В следующем примере символ %
будет заменён на значение v_job_id
:
RAISE NOTICE 'Вызов функции cs_create_job(%)', v_job_id;
При помощи USING
и последующих элементов параметр
= выражение
можно добавить дополнительную информацию к отчёту об ошибке. Все выражения
представляют собой строковые выражения. Возможные ключевые слова для параметра
следующие:
MESSAGE
#Устанавливает текст сообщения об ошибке. Этот параметр не может использоваться, если в команде
RAISE
присутствуетформат
передUSING
.DETAIL
#Предоставляет детальное сообщение об ошибке.
HINT
#Предоставляет подсказку по вызванной ошибке.
ERRCODE
#Устанавливает код ошибки (
SQLSTATE
). Код ошибки задаётся либо по имени, как показано в Приложении A, или напрямую, пятисимвольный кодSQLSTATE
.COLUMN
CONSTRAINT
DATATYPE
TABLE
SCHEMA
#Предоставляет имя соответствующего объекта, связанного с ошибкой.
Этот пример прерывает транзакцию и устанавливает сообщение об ошибке с подсказкой:
RAISE EXCEPTION 'Несуществующий ID --> %', user_id USING HINT = 'Проверьте ваш пользовательский 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 = 'ID пользователя уже существует: ' || user_id;
Ещё один вариант — использовать RAISE USING
или RAISE
, а всё остальное записать в списке уровень
USINGUSING
.
И заключительный вариант, в котором RAISE
не имеет параметров вообще. Эта форма может использоваться только в секции EXCEPTION
блока и предназначена для того, чтобы повторно вызвать ошибку, которая сейчас перехвачена и обрабатывается.
Примечание
До версии PostgreSQL 9.1 команда RAISE
без параметров всегда вызывала ошибку с выходом из блока, содержащего активную секцию EXCEPTION
. Эту ошибку нельзя было перехватить, даже если RAISE
в секции EXCEPTION
поместить во вложенный блок со своей секцией EXCEPTION
. Это было сочтено удивительным и не совместимым с Oracle PL/SQL.
Если в команде RAISE EXCEPTION
не задано ни имя, ни код SQLSTATE
, по умолчанию выдаётся raise_exception
(P0001
). Если не задан текст сообщения, по умолчанию в качестве этого текста передаётся имя условия или код SQLSTATE.
Примечание
При задании SQLSTATE
кода необязательно использовать только список предопределённых кодов ошибок. В качестве кода ошибки может быть любое пятисимвольное значение, состоящее из цифр и/или ASCII символов в верхнем регистре, кроме 00000
. Не рекомендуется использовать коды ошибок, которые заканчиваются на 000
, потому что так обозначаются коды категорий. И чтобы их перехватить, нужно перехватывать целую категорию.
41.9.2. Проверка утверждений #
Оператор ASSERT
представляет удобное средство вставлять отладочные проверки в функции PL/pgSQL.
ASSERTусловие
[ ,сообщение
];
Здесь условие
— это логическое выражение, которое, как ожидается, должно быть всегда истинным; если это так, оператор ASSERT
больше ничего не делает. Если же оно возвращает ложь или NULL, этот оператор выдаёт исключение ASSERT_FAILURE
. (Если ошибка происходит при вычислении условия
, она выдаётся как обычная ошибка.)
Если в нём задаётся необязательное сообщение
, результат этого выражения (если он не NULL) заменяет сообщение об ошибке по умолчанию «assertion failed» (нарушение истинности), в случае, если условие
не выполняется. В обычном случае, когда условие утверждения выполняется, выражение сообщения
не вычисляется.
Проверку утверждений можно включить или отключить с помощью конфигурационного параметра plpgsql.check_asserts
, принимающего логическое значение; по умолчанию она включена (on
). Если этот параметр отключён (off
), операторы ASSERT
ничего не делают.
Учтите, что оператор ASSERT
предназначен для выявления программных дефектов, а не для вывода обычных ошибок (для этого используется оператор RAISE
, описанный выше).