Skip to content

Commit 40b449a

Browse files
tglsfdctglsfdc
committed
Allow CREATE EXTENSION to follow extension update paths.
Previously, to update an extension you had to produce both a version-update script and a new base installation script. It's become more and more obvious that that's tedious, duplicative, and error-prone. This patch attempts to improve matters by allowing the new base installation script to be omitted. CREATE EXTENSION will install a requested version if it can find a base script and a chain of update scripts that will get there. As in the existing update logic, shorter chains are preferred if there's more than one possibility, with an arbitrary tie-break rule for chains of equal length. Also adjust the pg_available_extension_versions view to show such versions as installable. While at it, refactor the code so that CASCADE processing works for extensions requested during ApplyExtensionUpdates(). Without this, addition of a new requirement in an updated extension would require creating a new base script, even if there was no other reason to do that. (It would be easy at this point to add a CASCADE option to ALTER EXTENSION UPDATE, to allow the same thing to happen during a manually-commanded version update, but I have not done that here.) Tom Lane, reviewed by Andres Freund Discussion: <20160905005919.jz2m2yh3und2dsuy@alap3.anarazel.de>
1 parent 28e5e56 commit 40b449a

File tree

2 files changed

+439
-210
lines changed

2 files changed

+439
-210
lines changed

‎doc/src/sgml/extend.sgml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -885,6 +885,47 @@ SELECT * FROM pg_extension_update_paths('<replaceable>extension_name</>');
885885
</para>
886886
</sect2>
887887

888+
<sect2>
889+
<title>Installing Extensions using Update Scripts</title>
890+
891+
<para>
892+
An extension that has been around for awhile will probably exist in
893+
several versions, for which the author will need to write update scripts.
894+
For example, if you have released a <literal>foo</> extension in
895+
versions <literal>1.0</>, <literal>1.1</>, and <literal>1.2</>, there
896+
should be update scripts <filename>foo--1.0--1.1.sql</>
897+
and <filename>foo--1.1--1.2.sql</>.
898+
Before <productname>PostgreSQL</> 10, it was necessary to also create
899+
new script files <filename>foo--1.1.sql</> and <filename>foo--1.2.sql</>
900+
that directly build the newer extension versions, or else the newer
901+
versions could not be installed directly, only by
902+
installing <literal>1.0</> and then updating. That was tedious and
903+
duplicative, but now it's unnecessary, because <command>CREATE
904+
EXTENSION</> can follow update chains automatically.
905+
For example, if only the script
906+
files <filename>foo--1.0.sql</>, <filename>foo--1.0--1.1.sql</>,
907+
and <filename>foo--1.1--1.2.sql</> are available then a request to
908+
install version <literal>1.2</> is honored by running those three
909+
scripts in sequence. The processing is the same as if you'd first
910+
installed <literal>1.0</> and then updated to <literal>1.2</>.
911+
(As with <command>ALTER EXTENSION UPDATE</>, if multiple pathways are
912+
available then the shortest is preferred.) Arranging an extension's
913+
script files in this style can reduce the amount of maintenance effort
914+
needed to produce small updates.
915+
</para>
916+
917+
<para>
918+
If you use secondary (version-specific) control files with an extension
919+
maintained in this style, keep in mind that each version needs a control
920+
file even if it has no stand-alone installation script, as that control
921+
file will determine how the implicit update to that version is performed.
922+
For example, if <filename>foo--1.0.control</> specifies <literal>requires
923+
= 'bar'</> but <literal>foo</>'s other control files do not, the
924+
extension's dependency on <literal>bar</> will be dropped when updating
925+
from <literal>1.0</> to another version.
926+
</para>
927+
</sect2>
928+
888929
<sect2 id="extend-extensions-example">
889930
<title>Extension Example</title>
890931

0 commit comments

Comments
 (0)