Debian Codegraph @

doc/src/sgml/ref/create_extension.sgml

raw
1 <!--
2 doc/src/sgml/ref/create_extension.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-createextension">
7 <indexterm zone="sql-createextension">
8 <primary>CREATE EXTENSION</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle>CREATE EXTENSION</refentrytitle>
13 <manvolnum>7</manvolnum>
14 <refmiscinfo>SQL - Language Statements</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>CREATE EXTENSION</refname>
19 <refpurpose>install an extension</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <synopsis>
24 CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name</replaceable>
25 [ WITH ] [ SCHEMA <replaceable class="parameter">schema_name</replaceable> ]
26 [ VERSION <replaceable class="parameter">version</replaceable> ]
27 [ CASCADE ]
28 </synopsis>
29 </refsynopsisdiv>
30
31 <refsect1>
32 <title>Description</title>
33
34 <para>
35 <command>CREATE EXTENSION</command> loads a new extension into the current
36 database. There must not be an extension of the same name already loaded.
37 </para>
38
39 <para>
40 Loading an extension essentially amounts to running the extension's script
41 file. The script will typically create new <acronym>SQL</acronym> objects such as
42 functions, data types, operators and index support methods.
43 <command>CREATE EXTENSION</command> additionally records the identities
44 of all the created objects, so that they can be dropped again if
45 <command>DROP EXTENSION</command> is issued.
46 </para>
47
48 <para>
49 The user who runs <command>CREATE EXTENSION</command> becomes the
50 owner of the extension for purposes of later privilege checks, and
51 normally also becomes the owner of any objects created by the
52 extension's script.
53 </para>
54
55 <para>
56 Loading an extension ordinarily requires the same privileges that would
57 be required to create its component objects. For many extensions this
58 means superuser privileges are needed.
59 However, if the extension is marked <firstterm>trusted</firstterm> in
60 its control file, then it can be installed by any user who has
61 <literal>CREATE</literal> privilege on the current database.
62 In this case the extension object itself will be owned by the calling
63 user, but the contained objects will be owned by the bootstrap superuser
64 (unless the extension's script explicitly assigns them to the calling
65 user). This configuration gives the calling user the right to drop the
66 extension, but not to modify individual objects within it.
67 </para>
68
69 </refsect1>
70
71 <refsect1>
72 <title>Parameters</title>
73
74 <variablelist>
75 <varlistentry>
76 <term><literal>IF NOT EXISTS</literal></term>
77 <listitem>
78 <para>
79 Do not throw an error if an extension with the same name already
80 exists. A notice is issued in this case. Note that there is no
81 guarantee that the existing extension is anything like the one that
82 would have been created from the currently-available script file.
83 </para>
84 </listitem>
85 </varlistentry>
86
87 <varlistentry>
88 <term><replaceable class="parameter">extension_name</replaceable></term>
89 <listitem>
90 <para>
91 The name of the extension to be
92 installed. <productname>PostgreSQL</productname> will create the
93 extension using details from the file <filename><replaceable
94 class="parameter">extension_name</replaceable>.control</filename>,
95 found via the server's extension control path (set by <xref
96 linkend="guc-extension-control-path"/>.)
97 </para>
98 </listitem>
99 </varlistentry>
100
101 <varlistentry>
102 <term><replaceable class="parameter">schema_name</replaceable></term>
103 <listitem>
104 <para>
105 The name of the schema in which to install the extension's
106 objects, given that the extension allows its contents to be
107 relocated. The named schema must already exist.
108 If not specified, and the extension's control file does not specify a
109 schema either, the current default object creation schema is used.
110 </para>
111
112 <para>
113 If the extension specifies a <literal>schema</literal> parameter in its
114 control file, then that schema cannot be overridden with
115 a <literal>SCHEMA</literal> clause. Normally, an error will be raised if
116 a <literal>SCHEMA</literal> clause is given and it conflicts with the
117 extension's <literal>schema</literal> parameter. However, if
118 the <literal>CASCADE</literal> clause is also given,
119 then <replaceable class="parameter">schema_name</replaceable> is
120 ignored when it conflicts. The
121 given <replaceable class="parameter">schema_name</replaceable> will be
122 used for installation of any needed extensions that do not
123 specify <literal>schema</literal> in their control files.
124 </para>
125
126 <para>
127 Remember that the extension itself is not considered to be within any
128 schema: extensions have unqualified names that must be unique
129 database-wide. But objects belonging to the extension can be within
130 schemas.
131 </para>
132 </listitem>
133 </varlistentry>
134
135 <varlistentry>
136 <term><replaceable class="parameter">version</replaceable></term>
137 <listitem>
138 <para>
139 The version of the extension to install. This can be written as
140 either an identifier or a string literal. The default version is
141 whatever is specified in the extension's control file.
142 </para>
143 </listitem>
144 </varlistentry>
145
146 <varlistentry>
147 <term><literal>CASCADE</literal></term>
148 <listitem>
149 <para>
150 Automatically install any extensions that this extension depends on
151 that are not already installed. Their dependencies are likewise
152 automatically installed, recursively. The <literal>SCHEMA</literal> clause,
153 if given, applies to all extensions that get installed this way.
154 Other options of the statement are not applied to
155 automatically-installed extensions; in particular, their default
156 versions are always selected.
157 </para>
158 </listitem>
159 </varlistentry>
160 </variablelist>
161 </refsect1>
162
163 <refsect1>
164 <title>Notes</title>
165
166 <para>
167 Before you can use <command>CREATE EXTENSION</command> to load an extension
168 into a database, the extension's supporting files must be installed.
169 Information about installing the extensions supplied with
170 <productname>PostgreSQL</productname> can be found in
171 <link linkend="contrib">Additional Supplied Modules</link>.
172 </para>
173
174 <para>
175 The extensions currently available for loading can be identified from the
176 <link linkend="view-pg-available-extensions"><structname>pg_available_extensions</structname></link>
177 or
178 <link linkend="view-pg-available-extension-versions"><structname>pg_available_extension_versions</structname></link>
179 system views.
180 </para>
181
182 <caution>
183 <para>
184 Installing an extension as superuser requires trusting that the
185 extension's author wrote the extension installation script in a secure
186 fashion. It is not terribly difficult for a malicious user to create
187 trojan-horse objects that will compromise later execution of a
188 carelessly-written extension script, allowing that user to acquire
189 superuser privileges. However, trojan-horse objects are only hazardous
190 if they are in the <varname>search_path</varname> during script
191 execution, meaning that they are in the extension's installation target
192 schema or in the schema of some extension it depends on. Therefore, a
193 good rule of thumb when dealing with extensions whose scripts have not
194 been carefully vetted is to install them only into schemas for which
195 CREATE privilege has not been and will not be granted to any untrusted
196 users. Likewise for any extensions they depend on.
197 </para>
198
199 <para>
200 The extensions supplied with <productname>PostgreSQL</productname> are
201 believed to be secure against installation-time attacks of this sort,
202 except for a few that depend on other extensions. As stated in the
203 documentation for those extensions, they should be installed into secure
204 schemas, or installed into the same schemas as the extensions they
205 depend on, or both.
206 </para>
207 </caution>
208
209 <para>
210 For information about writing new extensions, see
211 <xref linkend="extend-extensions"/>.
212 </para>
213 </refsect1>
214
215 <refsect1>
216 <title>Examples</title>
217
218 <para>
219 Install the <link linkend="hstore">hstore</link> extension into the
220 current database, placing its objects in schema <literal>addons</literal>:
221 <programlisting>
222 CREATE EXTENSION hstore SCHEMA addons;
223 </programlisting>
224 Another way to accomplish the same thing:
225 <programlisting>
226 SET search_path = addons;
227 CREATE EXTENSION hstore;
228 </programlisting></para>
229 </refsect1>
230
231 <refsect1>
232 <title>Compatibility</title>
233
234 <para>
235 <command>CREATE EXTENSION</command> is a <productname>PostgreSQL</productname>
236 extension.
237 </para>
238 </refsect1>
239
240 <refsect1>
241 <title>See Also</title>
242
243 <simplelist type="inline">
244 <member><xref linkend="sql-alterextension"/></member>
245 <member><xref linkend="sql-dropextension"/></member>
246 </simplelist>
247 </refsect1>
248
249 </refentry>