diff options
Diffstat (limited to 'doc/src/sgml/html/sql-createextension.html')
| -rw-r--r-- | doc/src/sgml/html/sql-createextension.html | 128 |
1 files changed, 128 insertions, 0 deletions
diff --git a/doc/src/sgml/html/sql-createextension.html b/doc/src/sgml/html/sql-createextension.html new file mode 100644 index 0000000..ff9b4b3 --- /dev/null +++ b/doc/src/sgml/html/sql-createextension.html @@ -0,0 +1,128 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE EXTENSION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER" /><link rel="next" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE EXTENSION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATEEXTENSION"><div class="titlepage"></div><a id="id-1.9.3.64.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE EXTENSION</span></h2><p>CREATE EXTENSION — install an extension</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +CREATE EXTENSION [ IF NOT EXISTS ] <em class="replaceable"><code>extension_name</code></em> + [ WITH ] [ SCHEMA <em class="replaceable"><code>schema_name</code></em> ] + [ VERSION <em class="replaceable"><code>version</code></em> ] + [ CASCADE ] +</pre></div><div class="refsect1" id="id-1.9.3.64.5"><h2>Description</h2><p> + <code class="command">CREATE EXTENSION</code> loads a new extension into the current + database. There must not be an extension of the same name already loaded. + </p><p> + Loading an extension essentially amounts to running the extension's script + file. The script will typically create new <acronym class="acronym">SQL</acronym> objects such as + functions, data types, operators and index support methods. + <code class="command">CREATE EXTENSION</code> additionally records the identities + of all the created objects, so that they can be dropped again if + <code class="command">DROP EXTENSION</code> is issued. + </p><p> + The user who runs <code class="command">CREATE EXTENSION</code> becomes the + owner of the extension for purposes of later privilege checks, and + normally also becomes the owner of any objects created by the + extension's script. + </p><p> + Loading an extension ordinarily requires the same privileges that would + be required to create its component objects. For many extensions this + means superuser privileges are needed. + However, if the extension is marked <em class="firstterm">trusted</em> in + its control file, then it can be installed by any user who has + <code class="literal">CREATE</code> privilege on the current database. + In this case the extension object itself will be owned by the calling + user, but the contained objects will be owned by the bootstrap superuser + (unless the extension's script explicitly assigns them to the calling + user). This configuration gives the calling user the right to drop the + extension, but not to modify individual objects within it. + </p></div><div class="refsect1" id="id-1.9.3.64.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IF NOT EXISTS</code></span></dt><dd><p> + 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 + would have been created from the currently-available script file. + </p></dd><dt><span class="term"><em class="replaceable"><code>extension_name</code></em></span></dt><dd><p> + The name of the extension to be + installed. <span class="productname">PostgreSQL</span> will create the + extension using details from the file + <code class="literal">SHAREDIR/extension/</code><em class="replaceable"><code>extension_name</code></em><code class="literal">.control</code>. + </p></dd><dt><span class="term"><em class="replaceable"><code>schema_name</code></em></span></dt><dd><p> + 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. + </p><p> + If the extension specifies a <code class="literal">schema</code> parameter in its + control file, then that schema cannot be overridden with + a <code class="literal">SCHEMA</code> clause. Normally, an error will be raised if + a <code class="literal">SCHEMA</code> clause is given and it conflicts with the + extension's <code class="literal">schema</code> parameter. However, if + the <code class="literal">CASCADE</code> clause is also given, + then <em class="replaceable"><code>schema_name</code></em> is + ignored when it conflicts. The + given <em class="replaceable"><code>schema_name</code></em> will be + used for installation of any needed extensions that do not + specify <code class="literal">schema</code> in their control files. + </p><p> + 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. + </p></dd><dt><span class="term"><em class="replaceable"><code>version</code></em></span></dt><dd><p> + 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. + </p></dd><dt><span class="term"><code class="literal">CASCADE</code></span></dt><dd><p> + Automatically install any extensions that this extension depends on + that are not already installed. Their dependencies are likewise + automatically installed, recursively. The <code class="literal">SCHEMA</code> clause, + 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. + </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.64.7"><h2>Notes</h2><p> + Before you can use <code class="command">CREATE EXTENSION</code> to load an extension + into a database, the extension's supporting files must be installed. + Information about installing the extensions supplied with + <span class="productname">PostgreSQL</span> can be found in + <a class="link" href="contrib.html" title="Appendix F. Additional Supplied Modules">Additional Supplied Modules</a>. + </p><p> + The extensions currently available for loading can be identified from the + <a class="link" href="view-pg-available-extensions.html" title="54.2. pg_available_extensions"><code class="structname">pg_available_extensions</code></a> + or + <a class="link" href="view-pg-available-extension-versions.html" title="54.3. pg_available_extension_versions"><code class="structname">pg_available_extension_versions</code></a> + system views. + </p><div class="caution"><h3 class="title">Caution</h3><p> + Installing an extension as superuser requires trusting that the + extension's author wrote the extension installation script in a secure + fashion. It is not terribly difficult for a malicious user to create + trojan-horse objects that will compromise later execution of a + carelessly-written extension script, allowing that user to acquire + superuser privileges. However, trojan-horse objects are only hazardous + if they are in the <code class="varname">search_path</code> during script + execution, meaning that they are in the extension's installation target + schema or in the schema of some extension it depends on. Therefore, a + good rule of thumb when dealing with extensions whose scripts have not + been carefully vetted is to install them only into schemas for which + CREATE privilege has not been and will not be granted to any untrusted + users. Likewise for any extensions they depend on. + </p><p> + The extensions supplied with <span class="productname">PostgreSQL</span> are + believed to be secure against installation-time attacks of this sort, + except for a few that depend on other extensions. As stated in the + documentation for those extensions, they should be installed into secure + schemas, or installed into the same schemas as the extensions they + depend on, or both. + </p></div><p> + For information about writing new extensions, see + <a class="xref" href="extend-extensions.html" title="38.17. Packaging Related Objects into an Extension">Section 38.17</a>. + </p></div><div class="refsect1" id="id-1.9.3.64.8"><h2>Examples</h2><p> + Install the <a class="link" href="hstore.html" title="F.18. hstore">hstore</a> extension into the + current database, placing its objects in schema <code class="literal">addons</code>: +</p><pre class="programlisting"> +CREATE EXTENSION hstore SCHEMA addons; +</pre><p> + Another way to accomplish the same thing: +</p><pre class="programlisting"> +SET search_path = addons; +CREATE EXTENSION hstore; +</pre></div><div class="refsect1" id="id-1.9.3.64.9"><h2>Compatibility</h2><p> + <code class="command">CREATE EXTENSION</code> is a <span class="productname">PostgreSQL</span> + extension. + </p></div><div class="refsect1" id="id-1.9.3.64.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-alterextension.html" title="ALTER EXTENSION"><span class="refentrytitle">ALTER EXTENSION</span></a>, <a class="xref" href="sql-dropextension.html" title="DROP EXTENSION"><span class="refentrytitle">DROP EXTENSION</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createeventtrigger.html" title="CREATE EVENT TRIGGER">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createforeigndatawrapper.html" title="CREATE FOREIGN DATA WRAPPER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE EVENT TRIGGER </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE FOREIGN DATA WRAPPER</td></tr></table></div></body></html>
\ No newline at end of file |