2011-02-08 22:08:41 +01:00
|
|
|
<!--
|
|
|
|
doc/src/sgml/ref/create_extension.sgml
|
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refentry id="sql-createextension">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="sql-createextension">
|
|
|
|
<primary>CREATE EXTENSION</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2011-02-08 22:08:41 +01:00
|
|
|
<refmeta>
|
|
|
|
<refentrytitle>CREATE EXTENSION</refentrytitle>
|
|
|
|
<manvolnum>7</manvolnum>
|
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>CREATE EXTENSION</refname>
|
|
|
|
<refpurpose>install an extension</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2011-03-04 22:08:24 +01:00
|
|
|
CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name</replaceable>
|
2012-06-22 00:06:14 +02:00
|
|
|
[ WITH ] [ SCHEMA <replaceable class="parameter">schema_name</replaceable> ]
|
2011-02-12 03:25:20 +01:00
|
|
|
[ VERSION <replaceable class="parameter">version</replaceable> ]
|
|
|
|
[ FROM <replaceable class="parameter">old_version</replaceable> ]
|
2015-10-03 18:19:37 +02:00
|
|
|
[ CASCADE ]
|
2011-02-08 22:08:41 +01:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE EXTENSION</command> loads a new extension into the current
|
|
|
|
database. There must not be an extension of the same name already loaded.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Loading an extension essentially amounts to running the extension's script
|
2017-10-09 03:44:17 +02:00
|
|
|
file. The script will typically create new <acronym>SQL</acronym> objects such as
|
2011-02-08 22:08:41 +01:00
|
|
|
functions, data types, operators and index support methods.
|
|
|
|
<command>CREATE EXTENSION</command> additionally records the identities
|
|
|
|
of all the created objects, so that they can be dropped again if
|
|
|
|
<command>DROP EXTENSION</command> is issued.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2011-03-04 22:08:24 +01:00
|
|
|
Loading an extension requires the same privileges that would be
|
|
|
|
required to create its component objects. For most extensions this
|
|
|
|
means superuser or database owner privileges are needed.
|
|
|
|
The user who runs <command>CREATE EXTENSION</command> becomes the
|
|
|
|
owner of the extension for purposes of later privilege checks, as well
|
|
|
|
as the owner of any objects created by the extension's script.
|
2011-02-08 22:08:41 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
2011-03-04 22:08:24 +01:00
|
|
|
<varlistentry>
|
2017-10-09 03:44:17 +02:00
|
|
|
<term><literal>IF NOT EXISTS</literal></term>
|
2011-03-04 22:08:24 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Do not throw an error if an extension with the same name already
|
|
|
|
exists. A notice is issued in this case. Note that there is no
|
|
|
|
guarantee that the existing extension is anything like the one that
|
2011-04-13 08:56:33 +02:00
|
|
|
would have been created from the currently-available script file.
|
2011-03-04 22:08:24 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2011-02-08 22:08:41 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">extension_name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of the extension to be
|
|
|
|
installed. <productname>PostgreSQL</productname> will create the
|
|
|
|
extension using details from the file
|
2011-02-12 04:53:43 +01:00
|
|
|
<literal>SHAREDIR/extension/</literal><replaceable class="parameter">extension_name</replaceable><literal>.control</literal>.
|
2011-02-08 22:08:41 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2012-06-22 00:06:14 +02:00
|
|
|
<term><replaceable class="parameter">schema_name</replaceable></term>
|
2011-02-08 22:08:41 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name of the schema in which to install the extension's
|
|
|
|
objects, given that the extension allows its contents to be
|
|
|
|
relocated. The named schema must already exist.
|
|
|
|
If not specified, and the extension's control file does not specify a
|
|
|
|
schema either, the current default object creation schema is used.
|
|
|
|
</para>
|
2016-09-07 19:36:08 +02:00
|
|
|
|
2015-10-03 18:19:37 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
If the extension specifies a <literal>schema</literal> parameter in its
|
2016-09-07 19:36:08 +02:00
|
|
|
control file, then that schema cannot be overridden with
|
2017-10-09 03:44:17 +02:00
|
|
|
a <literal>SCHEMA</literal> clause. Normally, an error will be raised if
|
|
|
|
a <literal>SCHEMA</literal> clause is given and it conflicts with the
|
|
|
|
extension's <literal>schema</literal> parameter. However, if
|
|
|
|
the <literal>CASCADE</literal> clause is also given,
|
2016-09-07 19:36:08 +02:00
|
|
|
then <replaceable class="parameter">schema_name</replaceable> is
|
|
|
|
ignored when it conflicts. The
|
|
|
|
given <replaceable class="parameter">schema_name</replaceable> will be
|
|
|
|
used for installation of any needed extensions that do not
|
2017-10-09 03:44:17 +02:00
|
|
|
specify <literal>schema</literal> in their control files.
|
2015-10-03 18:19:37 +02:00
|
|
|
</para>
|
2016-09-07 19:36:08 +02:00
|
|
|
|
2013-04-05 04:37:25 +02:00
|
|
|
<para>
|
|
|
|
Remember that the extension itself is not considered to be within any
|
|
|
|
schema: extensions have unqualified names that must be unique
|
|
|
|
database-wide. But objects belonging to the extension can be within
|
|
|
|
schemas.
|
|
|
|
</para>
|
2011-02-08 22:08:41 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2011-02-12 03:25:20 +01:00
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">version</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The version of the extension to install. This can be written as
|
|
|
|
either an identifier or a string literal. The default version is
|
|
|
|
whatever is specified in the extension's control file.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">old_version</replaceable></term>
|
|
|
|
<listitem>
|
2016-09-07 19:36:08 +02:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>FROM</literal> <replaceable class="parameter">old_version</replaceable>
|
2011-02-12 03:25:20 +01:00
|
|
|
must be specified when, and only when, you are attempting to install
|
2017-10-09 03:44:17 +02:00
|
|
|
an extension that replaces an <quote>old style</quote> module that is just
|
2011-02-12 03:25:20 +01:00
|
|
|
a collection of objects not packaged into an extension. This option
|
2017-10-09 03:44:17 +02:00
|
|
|
causes <command>CREATE EXTENSION</command> to run an alternative installation
|
2011-02-12 03:25:20 +01:00
|
|
|
script that absorbs the existing objects into the extension, instead
|
2017-10-09 03:44:17 +02:00
|
|
|
of creating new objects. Be careful that <literal>SCHEMA</literal> specifies
|
2011-02-12 03:25:20 +01:00
|
|
|
the schema containing these pre-existing objects.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The value to use for <replaceable
|
|
|
|
class="parameter">old_version</replaceable> is determined by the
|
|
|
|
extension's author, and might vary if there is more than one version
|
|
|
|
of the old-style module that can be upgraded into an extension.
|
|
|
|
For the standard additional modules supplied with pre-9.1
|
2017-10-09 03:44:17 +02:00
|
|
|
<productname>PostgreSQL</productname>, use <literal>unpackaged</literal>
|
2011-02-12 03:25:20 +01:00
|
|
|
for <replaceable class="parameter">old_version</replaceable> when
|
|
|
|
updating a module to extension style.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2015-10-03 18:19:37 +02:00
|
|
|
|
|
|
|
<varlistentry>
|
2017-10-09 03:44:17 +02:00
|
|
|
<term><literal>CASCADE</literal></term>
|
2015-10-03 18:19:37 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2016-09-07 19:36:08 +02:00
|
|
|
Automatically install any extensions that this extension depends on
|
|
|
|
that are not already installed. Their dependencies are likewise
|
2017-10-09 03:44:17 +02:00
|
|
|
automatically installed, recursively. The <literal>SCHEMA</literal> clause,
|
2016-09-07 19:36:08 +02:00
|
|
|
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.
|
2015-10-03 18:19:37 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2011-02-08 22:08:41 +01:00
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
2011-04-13 08:56:33 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Before you can use <command>CREATE EXTENSION</command> to load an extension
|
2011-04-13 08:56:33 +02:00
|
|
|
into a database, the extension's supporting files must be installed.
|
|
|
|
Information about installing the extensions supplied with
|
|
|
|
<productname>PostgreSQL</productname> can be found in
|
|
|
|
<link linkend="contrib">Additional Supplied Modules</link>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The extensions currently available for loading can be identified from the
|
|
|
|
<link linkend="view-pg-available-extensions"><structname>pg_available_extensions</structname></link>
|
|
|
|
or
|
|
|
|
<link linkend="view-pg-available-extension-versions"><structname>pg_available_extension_versions</structname></link>
|
|
|
|
system views.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For information about writing new extensions, see
|
2017-11-23 15:39:47 +01:00
|
|
|
<xref linkend="extend-extensions"/>.
|
2011-04-13 08:56:33 +02:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2011-02-08 22:08:41 +01:00
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Install the <link linkend="hstore">hstore</link> extension into the
|
|
|
|
current database:
|
|
|
|
<programlisting>
|
|
|
|
CREATE EXTENSION hstore;
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
2011-02-12 03:25:20 +01:00
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Update a pre-9.1 installation of <literal>hstore</literal> into
|
2011-02-12 03:25:20 +01:00
|
|
|
extension style:
|
|
|
|
<programlisting>
|
|
|
|
CREATE EXTENSION hstore SCHEMA public FROM unpackaged;
|
|
|
|
</programlisting>
|
|
|
|
Be careful to specify the schema in which you installed the existing
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>hstore</literal> objects.
|
2011-02-12 03:25:20 +01:00
|
|
|
</para>
|
2011-02-08 22:08:41 +01:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>CREATE EXTENSION</command> is a <productname>PostgreSQL</productname>
|
2011-02-08 22:08:41 +01:00
|
|
|
extension.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2017-11-23 15:39:47 +01:00
|
|
|
<member><xref linkend="sql-alterextension"/></member>
|
|
|
|
<member><xref linkend="sql-dropextension"/></member>
|
2011-02-08 22:08:41 +01:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
</refentry>
|