From bd180b607927c7757af17cd6fce0e545e5c48584 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Wed, 7 Sep 2016 13:36:08 -0400 Subject: [PATCH] Doc: minor documentation improvements about extensions. Document the formerly-undocumented behavior that schema and comment control-file entries for an extension are honored only during initial installation, whereas other properties are also honored during updates. While at it, do some copy-editing on the recently-added docs for CREATE EXTENSION ... CASCADE, use links for some formerly vague cross references, and make a couple other minor improvements. Back-patch to 9.6 where CASCADE was added. The other parts of this could go further back, but they're probably not important enough to bother. --- doc/src/sgml/extend.sgml | 32 +++++++++------ doc/src/sgml/ref/create_extension.sgml | 54 +++++++++++--------------- 2 files changed, 42 insertions(+), 44 deletions(-) diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index f050ff1f66..df88380a23 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -335,11 +335,13 @@ by pg_dump. Such a change is usually only sensible if you concurrently make the same change in the extension's script file. (But there are special provisions for tables containing configuration - data; see below.) + data; see .) + In production situations, it's generally better to create an extension + update script to perform changes to extension member objects. - The extension script may set privileges on objects which are part of the + The extension script may set privileges on objects that are part of the extension via GRANT and REVOKE statements. The final set of privileges for each object (if any are set) will be stored in the @@ -453,9 +455,11 @@ comment (string) - A comment (any string) about the extension. Alternatively, - the comment can be set by means of the - command in the script file. + A comment (any string) about the extension. The comment is applied + when initially creating an extension, but not during extension updates + (since that might override user-added comments). Alternatively, + the extension's comment can be set by writing + a command in the script file. @@ -518,7 +522,7 @@ its contained objects into a different schema after initial creation of the extension. The default is false, i.e. the extension is not relocatable. - See below for more information. + See for more information. @@ -529,7 +533,10 @@ This parameter can only be set for non-relocatable extensions. It forces the extension to be loaded into exactly the named schema - and not any other. See below for more information. + and not any other. + The schema parameter is consulted only when + initially creating an extension, not during extension updates. + See for more information. @@ -562,7 +569,8 @@ 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 + script in ). + 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. @@ -580,7 +588,7 @@ - + Extension Relocatability @@ -678,7 +686,7 @@ SET LOCAL search_path TO @extschema@; - + Extension Configuration Tables @@ -762,7 +770,7 @@ SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entr out but the dump will not be able to be restored directly and user intervention will be required. - + Sequences associated with serial or bigserial columns need to be directly marked to dump their state. Marking their parent @@ -877,7 +885,7 @@ SELECT * FROM pg_extension_update_paths('extension_name'); - + Extension Example diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml index 007d8c9330..14e910115a 100644 --- a/doc/src/sgml/ref/create_extension.sgml +++ b/doc/src/sgml/ref/create_extension.sgml @@ -95,35 +95,21 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name If not specified, and the extension's control file does not specify a schema either, the current default object creation schema is used. + - If the extension specifies schema in its control file, - the schema cannot be overridden with SCHEMA clause. - The SCHEMA clause in this case works as follows: - - - - If schema_name matches - the schema in control file, it will be used normally as there is no - conflict. - - - - - If the CASCADE clause is given, the - schema_name will only - be used for the missing required extensions which do not specify - schema in their control files. - - - - - If schema_name is not - the same as the one in extension's control file and the - CASCADE clause is not given, error will be thrown. - - - + If the extension specifies a schema parameter in its + control file, then that schema cannot be overridden with + a SCHEMA clause. Normally, an error will be raised if + a SCHEMA clause is given and it conflicts with the + extension's schema parameter. However, if + the CASCADE clause is also given, + then schema_name is + ignored when it conflicts. The + given schema_name will be + used for installation of any needed extensions that do not + specify schema in their control files. + Remember that the extension itself is not considered to be within any schema: extensions have unqualified names that must be unique @@ -147,7 +133,8 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name old_version - FROM old_version + + FROM old_version must be specified when, and only when, you are attempting to install an extension that replaces an old style module that is just a collection of objects not packaged into an extension. This option @@ -174,10 +161,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] extension_name CASCADE - Try to install extension including the required dependencies - recursively. The SCHEMA option will be propagated - to the required extensions. Other options are not recursively - applied when using this clause. + Automatically install any extensions that this extension depends on + that are not already installed. Their dependencies are likewise + automatically installed, recursively. The SCHEMA clause, + if given, applies to all extensions that get installed this way. + Other options of the statement are not applied to + automatically-installed extensions; in particular, their default + versions are always selected.