2011-02-08 22:08:41 +01:00
|
|
|
<!--
|
|
|
|
doc/src/sgml/ref/create_extension.sgml
|
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
|
|
|
<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
|
|
|
|
file. The script will typically create new <acronym>SQL</> objects such as
|
|
|
|
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>
|
|
|
|
<term><literal>IF NOT EXISTS</></term>
|
|
|
|
<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>
|
2015-10-03 18:19:37 +02:00
|
|
|
<para>
|
|
|
|
If the extension specifies <literal>schema</> in its control file,
|
2016-01-28 08:47:36 +01:00
|
|
|
the schema cannot be overridden with <literal>SCHEMA</> clause.
|
2015-10-03 18:19:37 +02:00
|
|
|
The <literal>SCHEMA</> clause in this case works as follows:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If <replaceable class="parameter">schema_name</replaceable> matches
|
|
|
|
the schema in control file, it will be used normally as there is no
|
|
|
|
conflict.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If the <literal>CASCADE</> clause is given, the
|
|
|
|
<replaceable class="parameter">schema_name</replaceable> will only
|
|
|
|
be used for the missing required extensions which do not specify
|
|
|
|
<literal>schema</> in their control files.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
If <replaceable class="parameter">schema_name</replaceable> is not
|
|
|
|
the same as the one in extension's control file and the
|
|
|
|
<literal>CASCADE</> clause is not given, error will be thrown.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
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>
|
2011-08-07 09:49:45 +02:00
|
|
|
<para><literal>FROM</> <replaceable class="parameter">old_version</>
|
2011-02-12 03:25:20 +01:00
|
|
|
must be specified when, and only when, you are attempting to install
|
|
|
|
an extension that replaces an <quote>old style</> module that is just
|
|
|
|
a collection of objects not packaged into an extension. This option
|
|
|
|
causes <command>CREATE EXTENSION</> to run an alternative installation
|
|
|
|
script that absorbs the existing objects into the extension, instead
|
|
|
|
of creating new objects. Be careful that <literal>SCHEMA</> specifies
|
|
|
|
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
|
|
|
|
<productname>PostgreSQL</productname>, use <literal>unpackaged</>
|
|
|
|
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>
|
|
|
|
<term><literal>CASCADE</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Try to install extension including the required dependencies
|
|
|
|
recursively. The <literal>SCHEMA</> option will be propagated
|
|
|
|
to the required extensions. Other options are not recursively
|
|
|
|
applied when using this clause.
|
|
|
|
</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>
|
|
|
|
Before you can use <command>CREATE EXTENSION</> to load an extension
|
|
|
|
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
|
|
|
|
<xref linkend="extend-extensions">.
|
|
|
|
</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>
|
|
|
|
Update a pre-9.1 installation of <literal>hstore</> into
|
|
|
|
extension style:
|
|
|
|
<programlisting>
|
|
|
|
CREATE EXTENSION hstore SCHEMA public FROM unpackaged;
|
|
|
|
</programlisting>
|
|
|
|
Be careful to specify the schema in which you installed the existing
|
|
|
|
<literal>hstore</> objects.
|
|
|
|
</para>
|
2011-02-08 22:08:41 +01:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CREATE EXTENSION</command> is a <productname>PostgreSQL</>
|
|
|
|
extension.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="sql-alterextension"></member>
|
|
|
|
<member><xref linkend="sql-dropextension"></member>
|
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
</refentry>
|