Throw a useful error message if an extension script file is fed to psql.

We have seen one too many reports of people trying to use 9.1 extension
files in the old-fashioned way of sourcing them in psql.  Not only does
that usually not work (due to failure to substitute for MODULE_PATHNAME
and/or @extschema@), but if it did work they'd get a collection of loose
objects not an extension.  To prevent this, insert an \echo ... \quit
line that prints a suitable error message into each extension script file,
and teach commands/extension.c to ignore lines starting with \echo.
That should not only prevent any adverse consequences of loading a script
file the wrong way, but make it crystal clear to users that they need to
do it differently now.

Tom Lane, following an idea of Andrew Dunstan's.  Back-patch into 9.1
... there is not going to be much value in this if we wait till 9.2.

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 35a5ae8fd42..7079db3ed3f 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -523,6 +523,17 @@
     </para>
 
     <para>
+     An extension's <acronym>SQL</> script files can also contain lines
+     beginning with <literal>\echo</>, which will be ignored (treated as
+     comments) by the extension mechanism.  This provision is commonly used
+     to throw an error if the script file is fed to <application>psql</>
+     rather than being loaded via <command>CREATE EXTENSION</> (see example
+     script below).  Without that, users might accidentally load the
+     extension's contents as <quote>loose</> objects rather than as an
+     extension, a state of affairs that's a bit tedious to recover from.
+    </para>
+
+    <para>
      While the script files can contain any characters allowed by the specified
      encoding, control files should contain only plain ASCII, because there
      is no way for <productname>PostgreSQL</> to know what encoding a
@@ -808,6 +819,9 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
      The script file <filename>pair--1.0.sql</> looks like this:
 
 <programlisting><![CDATA[
+-- complain if script is sourced in psql, rather than via CREATE EXTENSION
+\echo Use "CREATE EXTENSION pair" to load this file. \quit
+
 CREATE TYPE pair AS ( k text, v text );
 
 CREATE OR REPLACE FUNCTION pair(anyelement, text)