From b488daf0d59614e801059e3558f73b65b0cf7e06 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Thu, 19 Jun 2014 12:33:56 -0400
Subject: [PATCH] Document SQL functions' behavior of parsing the whole
 function at once.

Haribabu Kommi, somewhat rewritten by me
---
 doc/src/sgml/xfunc.sgml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 941b101f393..d759f3746b2 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -143,6 +143,21 @@ SELECT clean_emp();
 </screen>
     </para>
 
+    <note>
+     <para>
+      The entire body of a SQL function is parsed before any of it is
+      executed.  While a SQL function can contain commands that alter
+      the system catalogs (e.g., <command>CREATE TABLE</>), the effects
+      of such commands will not be visible during parse analysis of
+      later commands in the function.  Thus, for example,
+      <literal>CREATE TABLE foo (...); INSERT INTO foo VALUES(...);</literal>
+      will not work as desired if packaged up into a single SQL function,
+      since <structname>foo</> won't exist yet when the <command>INSERT</>
+      command is parsed.  It's recommended to use <application>PL/PgSQL</>
+      instead of a SQL function in this type of situation.
+     </para>
+   </note>
+
    <para>
     The syntax of the <command>CREATE FUNCTION</command> command requires
     the function body to be written as a string constant.  It is usually