From 458857cc9d7d00711b272a0dabbcb591b506d6b8 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 12 Oct 2011 15:45:03 -0400 Subject: 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. --- doc/src/sgml/extend.sgml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc/src') 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 @@ -522,6 +522,17 @@ script files are implicitly executed within a transaction block. + + An extension's SQL script files can also contain lines + beginning with \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 psql + rather than being loaded via CREATE EXTENSION (see example + script below). Without that, users might accidentally load the + extension's contents as loose objects rather than as an + extension, a state of affairs that's a bit tedious to recover from. + + While the script files can contain any characters allowed by the specified encoding, control files should contain only plain ASCII, because there @@ -808,6 +819,9 @@ SELECT * FROM pg_extension_update_paths('extension_name'); The script file pair--1.0.sql looks like this: