diff options
Diffstat (limited to 'doc/src/sgml/contrib.sgml')
| -rw-r--r-- | doc/src/sgml/contrib.sgml | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml new file mode 100644 index 0000000..922421a --- /dev/null +++ b/doc/src/sgml/contrib.sgml @@ -0,0 +1,238 @@ +<!-- doc/src/sgml/contrib.sgml --> + +<appendix id="contrib"> + <title>Additional Supplied Modules and Extensions</title> + + <para> + This appendix and the next one contain information on the + optional components + found in the <literal>contrib</literal> directory of the + <productname>PostgreSQL</productname> distribution. + These include porting tools, analysis utilities, + and plug-in features that are not part of the core PostgreSQL system. + They are separate mainly + because they address a limited audience or are too experimental + to be part of the main source tree. This does not preclude their + usefulness. + </para> + + <para> + This appendix covers extensions and other server plug-in module + libraries found in + <literal>contrib</literal>. <xref linkend="contrib-prog"/> covers utility + programs. + </para> + + <para> + When building from the source distribution, these optional + components are not built + automatically, unless you build the "world" target + (see <xref linkend="build"/>). + You can build and install all of them by running: +<screen> +<userinput>make</userinput> +<userinput>make install</userinput> +</screen> + in the <literal>contrib</literal> directory of a configured source tree; + or to build and install + just one selected module, do the same in that module's subdirectory. + Many of the modules have regression tests, which can be executed by + running: +<screen> +<userinput>make check</userinput> +</screen> + before installation or +<screen> +<userinput>make installcheck</userinput> +</screen> + once you have a <productname>PostgreSQL</productname> server running. + </para> + + <para> + If you are using a pre-packaged version of <productname>PostgreSQL</productname>, + these components are typically made available as a separate subpackage, + such as <literal>postgresql-contrib</literal>. + </para> + + <para> + Many components supply new user-defined functions, operators, or types, + packaged as <firstterm>extensions</firstterm>. + To make use of one of these extensions, after you have installed the code + you need to register the new SQL objects in the database system. + This is done by executing + a <xref linkend="sql-createextension"/> command. In a fresh database, + you can simply do + +<programlisting> +CREATE EXTENSION <replaceable>extension_name</replaceable>; +</programlisting> + + This command registers the new SQL objects in the current database only, + so you need to run it in every database in which you want + the extension's facilities to be available. Alternatively, run it in + database <literal>template1</literal> so that the extension will be copied into + subsequently-created databases by default. + </para> + + <para> + For all extensions, the <command>CREATE EXTENSION</command> command must be + run by a database superuser, unless the extension is + considered <quote>trusted</quote>. Trusted extensions can be run by any + user who has <literal>CREATE</literal> privilege on the current + database. Extensions that are trusted are identified as such in the + sections that follow. Generally, trusted extensions are ones that cannot + provide access to outside-the-database functionality. + </para> + + <para id="contrib-trusted-extensions"> + The following extensions are trusted in a default installation: + + <simplelist type="vert" columns="4"> + <member><xref linkend="btree-gin"/></member> + <member><xref linkend="btree-gist"/></member> + <member><xref linkend="citext"/></member> + <member><xref linkend="cube"/></member> + <member><xref linkend="dict-int"/></member> + <member><xref linkend="fuzzystrmatch"/></member> + <member><xref linkend="hstore"/></member> + <member><xref linkend="intarray"/></member> + <member><xref linkend="isn"/></member> + <member><xref linkend="lo"/></member> + <member><xref linkend="ltree"/></member> + <member><xref linkend="pgcrypto"/></member> + <member><xref linkend="pgtrgm"/></member> + <member><xref linkend="seg"/></member> + <member><xref linkend="tablefunc"/></member> + <member><xref linkend="tcn"/></member> + <member><xref linkend="tsm-system-rows"/></member> + <member><xref linkend="tsm-system-time"/></member> + <member><xref linkend="unaccent"/></member> + <member><xref linkend="uuid-ossp"/></member> + </simplelist> + </para> + + <para> + Many extensions allow you to install their objects in a schema of your + choice. To do that, add <literal>SCHEMA + <replaceable>schema_name</replaceable></literal> to the <command>CREATE EXTENSION</command> + command. By default, the objects will be placed in your current creation + target schema, which in turn defaults to <literal>public</literal>. + </para> + + <para> + Note, however, that some of these components are not <quote>extensions</quote> + in this sense, but are loaded into the server in some other way, for instance + by way of + <xref linkend="guc-shared-preload-libraries"/>. See the documentation of each + component for details. + </para> + + &adminpack; + &amcheck; + &auth-delay; + &auto-explain; + &basebackup-to-shell; + &basic-archive; + &bloom; + &btree-gin; + &btree-gist; + &citext; + &cube; + &dblink; + &dict-int; + &dict-xsyn; + &earthdistance; + &file-fdw; + &fuzzystrmatch; + &hstore; + &intagg; + &intarray; + &isn; + &lo; + <ree; + &oldsnapshot; + &pageinspect; + &passwordcheck; + &pgbuffercache; + &pgcrypto; + &pgfreespacemap; + &pgprewarm; + &pgrowlocks; + &pgstatstatements; + &pgstattuple; + &pgsurgery; + &pgtrgm; + &pgvisibility; + &pgwalinspect; + &postgres-fdw; + &seg; + &sepgsql; + &contrib-spi; + &sslinfo; + &tablefunc; + &tcn; + &test-decoding; + &tsm-system-rows; + &tsm-system-time; + &unaccent; + &uuid-ossp; + &xml2; + +</appendix> + +<!-- +These are two separate appendixes because it is difficult to mix regular +sections (for extensions) and refentries (for programs) in one chapter or +appendix. And we do want the programs as refentries so that we can produce man +pages. +--> + +<appendix id="contrib-prog"> + <title>Additional Supplied Programs</title> + + <para> + This appendix and the previous one contain information regarding the modules that + can be found in the <literal>contrib</literal> directory of the + <productname>PostgreSQL</productname> distribution. See <xref linkend="contrib"/> for + more information about the <literal>contrib</literal> section in general and + server extensions and plug-ins found in <literal>contrib</literal> + specifically. + </para> + + <para> + This appendix covers utility programs found in <literal>contrib</literal>. + Once installed, either from source or a packaging system, they are found in + the <filename>bin</filename> directory of the + <productname>PostgreSQL</productname> installation and can be used like any + other program. + </para> + + <sect1 id="contrib-prog-client"> + <title>Client Applications</title> + + <para> + This section covers <productname>PostgreSQL</productname> client + applications in <literal>contrib</literal>. They can be run from anywhere, + independent of where the database server resides. See + also <xref linkend="reference-client"/> for information about client + applications that are part of the core <productname>PostgreSQL</productname> + distribution. + </para> + + &oid2name; + &vacuumlo; + </sect1> + + <sect1 id="contrib-prog-server"> + <title>Server Applications</title> + + <para> + Some applications run on the <productname>PostgreSQL</productname> server + itself. Currently, no such applications are included in the + <literal>contrib</literal> directory. See also <xref + linkend="reference-server"/> for information about server applications that + are part of the core <productname>PostgreSQL</productname> distribution. + </para> + + </sect1> +</appendix> |