From 27d5d7ab10086d833e3df251951cf63c392b8bca Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sun, 13 Feb 2011 13:03:41 -0500 Subject: Change the naming convention for extension files to use double dashes. This allows us to have an unambiguous rule for deconstructing the names of script files and secondary control files, without having to forbid extension and version names from containing any dashes. We do have to forbid them from containing double dashes or leading/trailing dashes, but neither restriction is likely to bother anyone in practice. Per discussion, this seems like a better solution overall than the original design. --- doc/src/sgml/extend.sgml | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index 394aa879002..50924a78f0e 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -368,8 +368,8 @@ installation's SHAREDIR/extension directory. There must also be at least one SQL script file, which follows the naming pattern - extension-version.sql - (for example, foo-1.0.sql for version 1.0 of + extension--version.sql + (for example, foo--1.0.sql for version 1.0 of extension foo). By default, the script file(s) are also placed in the SHAREDIR/extension directory; but the control file can specify a different directory for the script file(s). @@ -378,7 +378,7 @@ The file format for an extension control file is the same as for the postgresql.conf file, namely a list of - parameter-name = value + parameter_name = value assignments, one per line. Blank lines and comments introduced by # are allowed. Be sure to quote any value that is not a single word or number. @@ -477,7 +477,7 @@ In addition to the primary control file extension.control, an extension can have secondary control files named in the style - extension-version.control. + extension--version.control. If supplied, these must be located in the script file directory. Secondary control files follow the same format as the primary control file. Any parameters set in a secondary control file override the @@ -671,15 +671,15 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr dynamically from one version to the next, you should provide update scripts that make the necessary changes to go from one version to the next. Update scripts have names following the pattern - extension-oldversion-newversion.sql - (for example, foo-1.0-1.1.sql contains the commands to modify + extension--oldversion--newversion.sql + (for example, foo--1.0--1.1.sql contains the commands to modify version 1.0 of extension foo into version 1.1). Given that a suitable update script is available, the command - ALTER EXTENSION ... UPDATE will update an installed extension + ALTER EXTENSION UPDATE will update an installed extension to the specified new version. The update script is run in the same environment that CREATE EXTENSION provides for installation scripts: in particular, search_path is set up in the same @@ -712,7 +712,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr class="parameter">old_version option, which causes it to not run the normal installation script for the target version, but instead the update script named - extension-old_version-target_version.sql. + extension--old_version--target_version.sql. The choice of the dummy version name to use as old_version is up to the extension author, though unpackaged is a common convention. If you have multiple @@ -723,7 +723,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr ALTER EXTENSION is able to execute sequences of update script files to achieve a requested update. For example, if only - foo-1.0-1.1.sql and foo-1.1-2.0.sql are + foo--1.0--1.1.sql and foo--1.1--2.0.sql are available, ALTER EXTENSION will apply them in sequence if an update to version 2.0 is requested when 1.0 is currently installed. @@ -734,11 +734,13 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr of version names: for example, it does not know whether 1.1 follows 1.0. It just matches up the available version names and follows the path that requires applying the fewest update scripts. + (A version name can actually be any string that doesn't contain + -- or leading or trailing -.) Sometimes it is useful to provide downgrade scripts, for - example foo-1.1-1.0.sql to allow reverting the changes + example foo--1.1--1.0.sql to allow reverting the changes associated with version 1.1. If you do that, be careful of the possibility that a downgrade script might unexpectedly get applied because it yields a shorter path. The risky case is where @@ -761,7 +763,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr - The script file pair-1.0.sql looks like this: + The script file pair--1.0.sql looks like this: EXTENSION = pair -DATA = pair-1.0.sql +DATA = pair--1.0.sql PG_CONFIG = pg_config PGXS := $(shell $(PG_CONFIG) --pgxs) @@ -860,7 +862,7 @@ include $(PGXS) MODULES = isbn_issn EXTENSION = isbn_issn -DATA_built = isbn_issn-1.0.sql +DATA = isbn_issn--1.0.sql DOCS = README.isbn_issn PG_CONFIG = pg_config -- cgit v1.2.3