From a4847fc3ef139ba9a8ffebb6ffa06ee72078ffa2 Mon Sep 17 00:00:00 2001
From: Tom Lane
Date: Wed, 25 Mar 2015 19:05:20 -0400
Subject: Add an ASSERT statement in plpgsql.

This is meant to make it easier to insert simple debugging cross-checks
in plpgsql functions.

Pavel Stehule, reviewed by Jim Nasby
---
 doc/src/sgml/plpgsql.sgml | 77 ++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 73 insertions(+), 4 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 9fc2a2f498b..d36acf6d996 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2562,8 +2562,9 @@ END;
      those shown in <xref linkend="errcodes-appendix">.  A category
      name matches any error within its category.  The special
      condition name <literal>OTHERS</> matches every error type except
-     <literal>QUERY_CANCELED</>.  (It is possible, but often unwise,
-     to trap <literal>QUERY_CANCELED</> by name.)  Condition names are
+     <literal>QUERY_CANCELED</> and <literal>ASSERT_FAILURE</>.
+     (It is possible, but often unwise, to trap those two error types
+     by name.)  Condition names are
      not case-sensitive.  Also, an error condition can be specified
      by <literal>SQLSTATE</> code; for example these are equivalent:
 <programlisting>
@@ -3387,8 +3388,12 @@ END LOOP <optional> <replaceable>label</replaceable> </optional>;
   <sect1 id="plpgsql-errors-and-messages">
    <title>Errors and Messages</title>
 
+  <sect2 id="plpgsql-statements-raise">
+   <title>Reporting Errors and Messages</title>
+
    <indexterm>
     <primary>RAISE</primary>
+    <secondary>in PL/pgSQL</secondary>
    </indexterm>
 
    <indexterm>
@@ -3580,6 +3585,67 @@ RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
     </para>
    </note>
 
+  </sect2>
+
+  <sect2 id="plpgsql-statements-assert">
+   <title>Checking Assertions</title>
+
+   <indexterm>
+    <primary>ASSERT</primary>
+    <secondary>in PL/pgSQL</secondary>
+   </indexterm>
+
+   <indexterm>
+    <primary>assertions</primary>
+    <secondary>in PL/pgSQL</secondary>
+   </indexterm>
+
+   <indexterm>
+    <primary><varname>plpgsql.check_asserts</> configuration parameter</primary>
+   </indexterm>
+
+   <para>
+    The <command>ASSERT</command> statement is a convenient shorthand for
+    inserting debugging checks into <application>PL/pgSQL</application>
+    functions.
+
+<synopsis>
+ASSERT <replaceable class="parameter">condition</replaceable> <optional> , <replaceable class="parameter">message</replaceable> </optional>;
+</synopsis>
+
+    The <replaceable class="parameter">condition</replaceable> is a boolean
+    expression that is expected to always evaluate to TRUE; if it does,
+    the <command>ASSERT</command> statement does nothing further.  If the
+    result is FALSE or NULL, then an <literal>ASSERT_FAILURE</> exception
+    is raised.  (If an error occurs while evaluating
+    the <replaceable class="parameter">condition</replaceable>, it is
+    reported as a normal error.)
+   </para>
+
+   <para>
+    If the optional <replaceable class="parameter">message</replaceable> is
+    provided, it is an expression whose result (if not null) replaces the
+    default error message text <quote>assertion failed</>, should
+    the <replaceable class="parameter">condition</replaceable> fail.
+    The <replaceable class="parameter">message</replaceable> expression is
+    not evaluated in the normal case where the assertion succeeds.
+   </para>
+
+   <para>
+    Testing of assertions can be enabled or disabled via the configuration
+    parameter <literal>plpgsql.check_asserts</>, which takes a boolean
+    value; the default is <literal>on</>.  If this parameter
+    is <literal>off</> then <command>ASSERT</> statements do nothing.
+   </para>
+
+   <para>
+    Note that <command>ASSERT</command> is meant for detecting program
+    bugs, not for reporting ordinary error conditions.  Use
+    the <command>RAISE</> statement, described above, for that.
+   </para>
+
+  </sect2>
+
  </sect1>
 
  <sect1 id="plpgsql-trigger">
@@ -5075,8 +5141,7 @@ $func$ LANGUAGE plpgsql;
     <productname>PostgreSQL</> does not have a built-in
     <function>instr</function> function, but you can create one
     using a combination of other
-    functions.<indexterm><primary>instr</></indexterm> In <xref
-    linkend="plpgsql-porting-appendix"> there is a
+    functions. In <xref linkend="plpgsql-porting-appendix"> there is a
     <application>PL/pgSQL</application> implementation of
     <function>instr</function> that you can use to make your porting
     easier.
@@ -5409,6 +5474,10 @@ $$ LANGUAGE plpgsql STRICT IMMUTABLE;
     your porting efforts.
    </para>
 
+   <indexterm>
+    <primary><function>instr</> function</primary>
+   </indexterm>
+
 <programlisting>
 --
 -- instr functions that mimic Oracle's counterpart
-- 
cgit v1.2.3