From f1fb4b0e63a677cdc86de667c75142b88a4edb65 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 14 Feb 2011 01:10:44 -0500
Subject: [PATCH] Fix obsolete references to old-style contrib installation
methods.
---
doc/src/sgml/contrib-spi.sgml | 15 ++++++----
doc/src/sgml/contrib.sgml | 47 +++++++++++++++++-------------
doc/src/sgml/dict-int.sgml | 4 +--
doc/src/sgml/dict-xsyn.sgml | 4 +--
doc/src/sgml/earthdistance.sgml | 2 +-
doc/src/sgml/hstore.sgml | 6 ----
doc/src/sgml/pgstatstatements.sgml | 2 +-
doc/src/sgml/tablefunc.sgml | 4 ++-
doc/src/sgml/test-parser.sgml | 4 +--
doc/src/sgml/tsearch2.sgml | 2 +-
doc/src/sgml/unaccent.sgml | 2 +-
11 files changed, 50 insertions(+), 42 deletions(-)
diff --git a/doc/src/sgml/contrib-spi.sgml b/doc/src/sgml/contrib-spi.sgml
index 85980f6e551..55e5ce26492 100644
--- a/doc/src/sgml/contrib-spi.sgml
+++ b/doc/src/sgml/contrib-spi.sgml
@@ -17,8 +17,13 @@
below) while creating a trigger.
</para>
+ <para>
+ Each of the groups of functions described below is provided as a
+ separately-installable extension.
+ </para>
+
<sect2>
- <title>refint.c — Functions for Implementing Referential Integrity</title>
+ <title>refint — Functions for Implementing Referential Integrity</title>
<para>
<function>check_primary_key()</> and
@@ -59,7 +64,7 @@
</sect2>
<sect2>
- <title>timetravel.c — Functions for Implementing Time Travel</title>
+ <title>timetravel — Functions for Implementing Time Travel</title>
<para>
Long ago, <productname>PostgreSQL</> had a built-in time travel feature
@@ -152,7 +157,7 @@ CREATE TABLE mytab (
</sect2>
<sect2>
- <title>autoinc.c — Functions for Autoincrementing Fields</title>
+ <title>autoinc — Functions for Autoincrementing Fields</title>
<para>
<function>autoinc()</> is a trigger that stores the next value of
@@ -179,7 +184,7 @@ CREATE TABLE mytab (
</sect2>
<sect2>
- <title>insert_username.c — Functions for Tracking Who Changed a Table</title>
+ <title>insert_username — Functions for Tracking Who Changed a Table</title>
<para>
<function>insert_username()</> is a trigger that stores the current
@@ -200,7 +205,7 @@ CREATE TABLE mytab (
</sect2>
<sect2>
- <title>moddatetime.c — Functions for Tracking Last Modification Time</title>
+ <title>moddatetime — Functions for Tracking Last Modification Time</title>
<para>
<function>moddatetime()</> is a trigger that stores the current
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index 75d08d5f695..4504ab1749d 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -46,38 +46,45 @@
<para>
Many modules supply new user-defined functions, operators, or types.
To make use of one of these modules, after you have installed the code
- you need to register the new objects in the database
- system by running the SQL commands in the <literal>.sql</> file
- supplied by the module. For example,
+ you need to register the new SQL objects in the database system.
+ In <productname>PostgreSQL</> 9.1 and later, this is done by executing
+ a <xref linkend="sql-createextension"> command. In a fresh database,
+ you can simply do
<programlisting>
-psql -d dbname -f <replaceable>SHAREDIR</>/contrib/<replaceable>module</>.sql
+CREATE EXTENSION <replaceable>module_name</>;
</programlisting>
- Here, <replaceable>SHAREDIR</> means the installation's <quote>share</>
- directory (<literal>pg_config --sharedir</> will tell you what this is).
- In most cases the script must be run by a database superuser.
- </para>
-
- <para>
- You need to run the <literal>.sql</> file in each database that you want
+ This command must be run by a database superuser. This registers the
+ new SQL objects in the current database only, so you need to run this
+ command in each database that you want
the module's facilities to be available in. Alternatively, run it in
- database <literal>template1</> so that the module will be copied into
+ database <literal>template1</> so that the extension will be copied into
subsequently-created databases by default.
</para>
<para>
- You can modify the first command in the <literal>.sql</> file to determine
- which schema within the database the module's objects will be created in.
- By default, they will be placed in <literal>public</>.
+ Many modules allow you to install their objects in a schema of your
+ choice. To do that, add <literal>SCHEMA
+ <replaceable>schema_name</></literal> to the <command>CREATE EXTENSION</>
+ command. By default, the objects will be placed in your current creation
+ target schema, typically <literal>public</>.
</para>
<para>
- After a major-version upgrade of <productname>PostgreSQL</>, run the
- installation script again, even though the module's objects might have
- been brought forward from the old installation by dump and restore.
- This ensures that any new functions will be available and any needed
- corrections will be applied.
+ If your database was brought forward by dump and reload from a pre-9.1
+ version of <productname>PostgreSQL</>, and you had been using the pre-9.1
+ version of the module in it, you should instead do
+
+<programlisting>
+CREATE EXTENSION <replaceable>module_name</> FROM unpackaged;
+</programlisting>
+
+ This will update the pre-9.1 objects of the module into a proper
+ <firstterm>extension</> object. Future updates to the module will be
+ managed by <xref linkend="sql-alterextension">.
+ For more information about extension updates, see
+ <xref linkend="extend-extensions">.
</para>
&adminpack;
diff --git a/doc/src/sgml/dict-int.sgml b/doc/src/sgml/dict-int.sgml
index b1d69e1a4c8..17f98c05fa7 100644
--- a/doc/src/sgml/dict-int.sgml
+++ b/doc/src/sgml/dict-int.sgml
@@ -47,8 +47,8 @@
<title>Usage</title>
<para>
- Running the installation script creates a text search template
- <literal>intdict_template</> and a dictionary <literal>intdict</>
+ Installing the <literal>dict_int</> extension creates a text search
+ template <literal>intdict_template</> and a dictionary <literal>intdict</>
based on it, with the default parameters. You can alter the
parameters, for example
diff --git a/doc/src/sgml/dict-xsyn.sgml b/doc/src/sgml/dict-xsyn.sgml
index e77889e388e..23c5d983c1f 100644
--- a/doc/src/sgml/dict-xsyn.sgml
+++ b/doc/src/sgml/dict-xsyn.sgml
@@ -87,8 +87,8 @@ word syn1 syn2 syn3
<title>Usage</title>
<para>
- Running the installation script creates a text search template
- <literal>xsyn_template</> and a dictionary <literal>xsyn</>
+ Installing the <literal>dict_xsyn</> extension creates a text search
+ template <literal>xsyn_template</> and a dictionary <literal>xsyn</>
based on it, with default parameters. You can alter the
parameters, for example
diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml
index b43907615a8..5b50da0510b 100644
--- a/doc/src/sgml/earthdistance.sgml
+++ b/doc/src/sgml/earthdistance.sgml
@@ -10,7 +10,7 @@
<para>
The <filename>earthdistance</> module provides two different approaches to
calculating great circle distances on the surface of the Earth. The one
- described first depends on the <filename>cube</> package (which
+ described first depends on the <filename>cube</> module (which
<emphasis>must</> be installed before <filename>earthdistance</> can be
installed). The second one is based on the built-in <type>point</> data type,
using longitude and latitude for the coordinates.
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 6ccc9d664bc..f00b06aa7aa 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -553,12 +553,6 @@ SELECT key, count(*) FROM
<sect2>
<title>Compatibility</title>
- <para>
- <emphasis>When upgrading from older versions, always load the new
- version of this module into the database before restoring a dump.
- Otherwise, many new features will be unavailable.</emphasis>
- </para>
-
<para>
As of PostgreSQL 9.0, <type>hstore</> uses a different internal
representation than previous versions. This presents no obstacle for
diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml
index 58b37d243cd..8cff1020bb3 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -148,7 +148,7 @@
<para>
This view, and the function <function>pg_stat_statements_reset</>,
are available only in databases they have been specifically installed into
- by running the <filename>pg_stat_statements.sql</> install script.
+ by installing the <literal>pg_stat_statements</> extension.
However, statistics are tracked across all databases of the server
whenever the <filename>pg_stat_statements</filename> module is loaded
into the server, regardless of presence of the view.
diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml
index 65917f7d308..dfb932f501a 100644
--- a/doc/src/sgml/tablefunc.sgml
+++ b/doc/src/sgml/tablefunc.sgml
@@ -345,7 +345,9 @@ FROM crosstab3(
<listitem>
<para>
Create a composite type describing the desired output columns,
- similar to the examples in the installation script. Then define a
+ similar to the examples in
+ <filename>contrib/tablefunc/tablefunc--1.0.sql</>.
+ Then define a
unique function name accepting one <type>text</> parameter and returning
<type>setof your_type_name</>, but linking to the same underlying
<function>crosstab</> C function. For example, if your source data
diff --git a/doc/src/sgml/test-parser.sgml b/doc/src/sgml/test-parser.sgml
index 0c53a3a4133..0f2008cbe6b 100644
--- a/doc/src/sgml/test-parser.sgml
+++ b/doc/src/sgml/test-parser.sgml
@@ -35,8 +35,8 @@ mydb=# SELECT * FROM ts_token_type('testparser');
<title>Usage</title>
<para>
- Running the installation script creates a text search parser
- <literal>testparser</>. It has no user-configurable parameters.
+ Installing the <literal>test_parser</> extension creates a text search
+ parser <literal>testparser</>. It has no user-configurable parameters.
</para>
<para>
diff --git a/doc/src/sgml/tsearch2.sgml b/doc/src/sgml/tsearch2.sgml
index 1933e2b966b..8321c1efb4f 100644
--- a/doc/src/sgml/tsearch2.sgml
+++ b/doc/src/sgml/tsearch2.sgml
@@ -152,7 +152,7 @@
<emphasis>before</> loading the dump data! If your old installation
had the <application>tsearch2</> objects in a schema other
than <literal>public</>, be sure to adjust the
- <literal>tsearch2</literal> installation script so that the replacement
+ <command>CREATE EXTENSION</> command so that the replacement
objects are created in that same schema.
</para>
</step>
diff --git a/doc/src/sgml/unaccent.sgml b/doc/src/sgml/unaccent.sgml
index 2ad66f7ee13..9c34c0bbd2e 100644
--- a/doc/src/sgml/unaccent.sgml
+++ b/doc/src/sgml/unaccent.sgml
@@ -73,7 +73,7 @@
<title>Usage</title>
<para>
- Running the installation script <filename>unaccent.sql</> creates a text
+ Installing the <literal>unaccent</> extension creates a text
search template <literal>unaccent</> and a dictionary <literal>unaccent</>
based on it. The <literal>unaccent</> dictionary has the default
parameter setting <literal>RULES='unaccent'</>, which makes it immediately
--
GitLab