RAISE

Raises an error, warning, or notice with formatted message.

Category: error-handling

Syntax

RAISE [<level>] '<format_string>' [, <args>]
  [USING <option> = <value>, ...];

Description

## Overview RAISE sends a message at a specified severity level, optionally with structured metadata. At the EXCEPTION level, it aborts execution and raises an error that can be caught by an EXCEPTION handler. At lower levels (DEBUG, LOG, INFO, NOTICE, WARNING), it logs a message and continues execution. ## Behavior - The level determines the action taken: - DEBUG: logged via tracing at debug level. Execution continues. - LOG: logged via tracing at info level. Execution continues. - INFO: logged via tracing at info level. Execution continues. - NOTICE: logged with a [NOTICE] prefix. Execution continues. - WARNING: logged via tracing at warn level. Execution continues. - EXCEPTION (default): creates an Error::UserException with the formatted message and raises it, aborting the current block. Can be caught by EXCEPTION handlers. - The format string uses `%` as the placeholder character. Each `%` is replaced by the string representation of the next argument expression, evaluated in order. - USING options attach metadata to the error: - DETAIL and HINT are stored on the error object and retrievable via GET STACKED DIAGNOSTICS. - ERRCODE sets the SQL state code. - Other options (COLUMN, CONSTRAINT, TABLE, SCHEMA, DATATYPE) are parsed but their effect depends on the exception matching logic. - All non-EXCEPTION messages are added to the executor's message buffer, which is accessible to the GUI via the Messages tab. - A bare `RAISE;` (without level or message) inside an EXCEPTION handler re-raises the current exception. ## Differences from PostgreSQL - All non-EXCEPTION levels are treated as informational messages routed through Rust's tracing framework. PostgreSQL has a more granular client_min_messages setting that controls which levels are sent to the client. - The message buffer accumulates all messages for the block execution, whereas PostgreSQL sends them to the client incrementally.

Parameters

Name	Type	Description
`level`		Set the severity level: DEBUG, LOG, INFO, NOTICE, WARNING, or EXCEPTION (default).
`format_string`		Provide a format string with % placeholders that are substituted with argument values in order.
`options`		Attach structured metadata via USING: ERRCODE, DETAIL, HINT, MESSAGE, COLUMN, CONSTRAINT, DATATYPE, TABLE, SCHEMA.

Examples

DO $$
BEGIN
  RAISE NOTICE 'Processing started at %', now();
END;
$$;

DO $$
DECLARE
  input_val INT := -5;
BEGIN
  IF input_val < 0 THEN
    RAISE EXCEPTION 'Invalid input: %', input_val
      USING ERRCODE = 'P0001',
            HINT = 'Provide a non-negative integer';
  END IF;
END;
$$;

DO $$
DECLARE
  rec RECORD;
  processed INT := 0;
BEGIN
  FOR rec IN SELECT id, name FROM batch_items LOOP
    processed := processed + 1;
    IF processed % 1000 = 0 THEN
      RAISE NOTICE 'Processed % items', processed;
    END IF;
  END LOOP;
  RAISE INFO 'Complete: % items processed', processed;
END;
$$;

DO $$
BEGIN
  RAISE WARNING 'Deprecated function called'
    USING HINT = 'Use new_pipeline_runner() instead',
          DETAIL = 'This function will be removed in version 3.0';
END;
$$;

DO $$
BEGIN
  BEGIN
    RAISE EXCEPTION 'Something went wrong'
      USING DETAIL = 'Connection timed out after 30s',
            HINT = 'Check network connectivity';
  EXCEPTION
    WHEN OTHERS THEN
      RAISE NOTICE 'Caught error: %', SQLERRM;
  END;
END;
$$;

DO $$
BEGIN
  RAISE DEBUG 'Variable dump: x=%', 42;
  RAISE LOG 'Audit: user accessed table';
END;
$$;

Pitfalls

RAISE without a level defaults to EXCEPTION, which aborts execution. Always specify the level explicitly for non-error messages (NOTICE, WARNING, INFO).
Format string placeholders (%) are replaced by positional arguments. A mismatch between placeholder count and argument count produces garbled output or unreplaced % characters.
RAISE EXCEPTION inside a loop without a surrounding EXCEPTION handler aborts the entire block, not just the current iteration. Wrap the loop body in a sub-block with EXCEPTION if per-iteration error handling is needed.
USING ERRCODE expects a 5-character SQL state string. Invalid codes are accepted but may not match any WHEN clause in exception handlers.