From d9572c4e3b474031060189050e14ef384b94e001 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Tue, 8 Feb 2011 16:08:41 -0500 Subject: Core support for "extensions", which are packages of SQL objects. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This patch adds the server infrastructure to support extensions. There is still one significant loose end, namely how to make it play nice with pg_upgrade, so I am not yet committing the changes that would make all the contrib modules depend on this feature. In passing, fix a disturbingly large amount of breakage in AlterObjectNamespace() and callers. Dimitri Fontaine, reviewed by Anssi Kääriäinen, Itagaki Takahiro, Tom Lane, and numerous others --- doc/src/sgml/acronyms.sgml | 2 +- doc/src/sgml/catalogs.sgml | 195 +++++++++ doc/src/sgml/extend.sgml | 715 +++++++++++++++++++++++++++++++-- doc/src/sgml/ref/allfiles.sgml | 3 + doc/src/sgml/ref/alter_extension.sgml | 98 +++++ doc/src/sgml/ref/comment.sgml | 1 + doc/src/sgml/ref/create_extension.sgml | 118 ++++++ doc/src/sgml/ref/drop_extension.sgml | 121 ++++++ doc/src/sgml/ref/psql-ref.sgml | 14 +- doc/src/sgml/reference.sgml | 3 + doc/src/sgml/release-9.0.sgml | 5 +- doc/src/sgml/xfunc.sgml | 331 +++------------ 12 files changed, 1296 insertions(+), 310 deletions(-) create mode 100644 doc/src/sgml/ref/alter_extension.sgml create mode 100644 doc/src/sgml/ref/create_extension.sgml create mode 100644 doc/src/sgml/ref/drop_extension.sgml (limited to 'doc/src') diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml index d1ef489e366..8f6752f05d7 100644 --- a/doc/src/sgml/acronyms.sgml +++ b/doc/src/sgml/acronyms.sgml @@ -485,7 +485,7 @@ PGXS - PostgreSQL Extension System + PostgreSQL Extension System diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index f31662c2720..24aa22cbced 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -143,6 +143,11 @@ enum label and value definitions + + pg_extension + installed extensions + + pg_foreign_data_wrapper foreign-data wrapper definitions @@ -2679,6 +2684,21 @@ + + DEPENDENCY_EXTENSION (e) + + + The dependent object is a member of the extension that is + the referenced object (see + pg_extension). + The dependent object can be dropped only via + DROP EXTENSION on the referenced object. Functionally + this dependency type acts the same as an internal dependency, but + it's kept separate for clarity and to simplify pg_dump. + + + + DEPENDENCY_PIN (p) @@ -2848,6 +2868,101 @@ + + <structname>pg_extension</structname> + + + pg_extension + + + + The catalog pg_extension stores information + about the installed extensions. See + for details about extensions. + + + + <structname>pg_extension</> Columns + + + + + Name + Type + References + Description + + + + + + extname + name + + Name of the extension + + + + extowner + oid + pg_authid.oid + Owner of the extension + + + + extnamespace + oid + pg_namespace.oid + Schema containing the extension's exported objects + + + + extrelocatable + bool + + True if extension can be relocated to another schema + + + + extversion + text + + Version string for the extension, or NULL if none + + + + extconfig + oid[] + pg_class.oid + Array of regclass OIDs for the extension's configuration + table(s), or NULL if none + + + + extcondition + text[] + + Array of WHERE-clause filter conditions for the + extension's configuration table(s), or NULL if none + + + + +
+ + + Note that unlike most catalogs with a namespace column, + extnamespace is not meant to imply + that the extension belongs to that schema. Extension names are never + schema-qualified. Rather, extnamespace + indicates the schema that contains most or all of the extension's + objects. If extrelocatable is true, then + this schema must in fact contain all schema-qualifiable objects + belonging to the extension. + + + + <structname>pg_foreign_data_wrapper</structname> @@ -6191,6 +6306,11 @@ + + pg_available_extensions + available extensions + + pg_cursors open cursors @@ -6286,6 +6406,81 @@ + + <structname>pg_available_extensions</structname> + + + pg_available_extensions + + + + The pg_available_extensions view lists the + extensions that are available for installation. This view can only + be read by superusers. See also the + pg_extension + catalog, which shows the extensions currently installed. + + + + <structname>pg_available_extensions</> Columns + + + + + Name + Type + Description + + + + + + name + name + Extension name + + + + version + text + Version string from the extension's control file + + + + installed + text + Currently installed version of the extension, + or NULL if not installed + + + + schema + name + Name of the schema where the extension is installed, + or NULL if not installed + + + + relocatable + bool + True if extension can be relocated to another schema + + + + comment + text + Comment string from the extension's control file + + + +
+ + + The pg_available_extensions view is read only. + + + + <structname>pg_cursors</structname> diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml index 2033ae21ba5..206eb6b9017 100644 --- a/doc/src/sgml/extend.sgml +++ b/doc/src/sgml/extend.sgml @@ -38,6 +38,11 @@ operator classes for indexes (starting in ) + + + packages of related objects (starting in ) + + @@ -273,67 +278,701 @@ &xoper; &xindex; - - Using C++ for Extensibility - - C++ + + Packaging Related Objects into an Extension + + + extension - It is possible to use a compiler in C++ mode to build - PostgreSQL extensions by following these - guidelines: + A useful extension to PostgreSQL typically includes + multiple SQL objects; for example, a new datatype will require new + functions, new operators, and probably new index operator classes. + It is helpful to collect all these objects into a single package + to simplify database management. PostgreSQL calls + such a package an extension. To define an extension, + you need at least a script file that contains the + SQL commands to create the extension's objects, and a + control file that specifies a few basic properties + of the extension itself. If the extension includes C code, there + will typically also be a shared library file into which the C code + has been built. Once you have these files, a simple + command loads the objects into + your database. + + + + The advantage of using an extension, rather than just running the + SQL script to load a bunch of loose objects + into your database, is that PostgreSQL will then + understand that the objects of the extension go together. You can + drop all the objects with a single + command (no need to maintain a separate uninstall script). + Even more useful, pg_dump knows that it should not + dump the individual member objects of the extension — it will + just include a CREATE EXTENSION command in dumps, instead. + This vastly simplifies migration to a new version of the extension + that might contain more or different objects than the old version. + Note however that you must have the extension's control, script, and + other files available when loading such a dump into a new database. + + + + PostgreSQL will not let you drop an individual object + contained in an extension, except by dropping the whole extension. + Also, while you can change the definition of an extension member object + (for example, via CREATE OR REPLACE FUNCTION for a + function), bear in mind that the modified definition will not be dumped + by pg_dump. Such a change is usually only sensible if + you concurrently make the same change in the extension's script file. + (But there are special provisions for tables containing configuration + data; see below.) + + + + Extension Files + + + control file + + + + The command relies on a control + file for each extension, which must be named the same as the extension + with a suffix of .control, and must be placed in the + installation's SHAREDIR/contrib directory. There + must also be a SQL script file, which typically is + named after the extension with a suffix of .sql, and is also + placed in the SHAREDIR/contrib directory; but these + defaults can be overridden by the control file. + + + + The file format for an extension control file is the same as for the + postgresql.conf file, namely a list of + parameter-name = value + assignments, one per line. Blank lines and comments introduced by + # are allowed. Be sure to quote any value that is not + a single word or number. + + + + A control file can set the following parameters: + + + + + script (string) + + + The filename of the extension's SQL script. + Defaults to the same name as the control file, but with the + .sql extension. Unless an absolute path is + given, the name is relative to the SHAREDIR/contrib + directory. + + + + + + version (string) + + + The version of the extension. Any string can be given. + + + + + + comment (string) + + + A comment (any string) about the extension. Alternatively, + the comment can be set by means of the + command. + + + + + + requires (string) + + + A list of names of extensions that this extension depends on, + for example requires = 'foo, bar'. Those + extensions must be installed before this one can be installed. + + + + + + encoding (string) + + + The character set encoding used by the script file. This should + be specified if the script file contains any non-ASCII characters. + Otherwise the script will be assumed to be in the encoding of the + database it is loaded into. + + + + + + relocatable (boolean) + + + An extension is relocatable if it is possible to move + its contained objects into a different schema after initial creation + of the extension. The default is false, i.e. the + extension is not relocatable. + See below for more information. + + + + + + schema (string) + + + This parameter can only be set for non-relocatable extensions. + It forces the extension to be loaded into exactly the named schema + and not any other. See below for more information. + + + + + + + An extension's SQL script file can contain any SQL commands, + except for transaction control commands (BEGIN, + COMMIT, etc) and commands that cannot be executed inside a + transaction block (such as VACUUM). This is because the + script file is implicitly executed within a transaction block. + + + + While the script file can contain any characters allowed by the specified + encoding, the control file should contain only plain ASCII, because there + is no way for PostgreSQL to know what encoding the + control file is in. In practice this is only an issue if you want to + use non-ASCII characters in the extension's comment. Recommended + practice in that case is to not use the comment parameter + in the control file, but instead use COMMENT ON EXTENSION + within the script file to set the comment. + + + + + + Extension Relocatability + + + Users often wish to load the objects contained in an extension into a + different schema than the extension's author had in mind. There are + three supported levels of relocatability: + - All functions accessed by the backend must present a C interface - to the backend; these C functions can then call C++ functions. - For example, extern C linkage is required for - backend-accessed functions. This is also necessary for any - functions that are passed as pointers between the backend and - C++ code. - - - - - Free memory using the appropriate deallocation method. For example, - most backend memory is allocated using palloc(), so use - pfree() to free it, i.e. using C++ - delete() in such cases will fail. + A fully relocatable extension can be moved into another schema + at any time, even after it's been loaded into a database. + This is done with the ALTER EXTENSION SET SCHEMA + command, which automatically renames all the member objects into + the new schema. Normally, this is only possible if the extension + contains no internal assumptions about what schema any of its + objects are in. Also, the extension's objects must all be in one + schema to begin with (ignoring objects that do not belong to any + schema, such as procedural languages). Mark a fully relocatable + extension by setting relocatable = true in its control + file. + - Prevent exceptions from propagating into the C code (use a - catch-all block at the top level of all extern C - functions). This is necessary even if the C++ code does not - throw any exceptions because events like out-of-memory still - throw exceptions. Any exceptions must be caught and appropriate - errors passed back to the C interface. If possible, compile C++ - with + - If calling backend functions from C++ code, be sure that the - C++ call stack contains only plain old data structures - (POD). This is necessary because backend errors - generate a distant longjmp() that does not properly - unroll a C++ call stack with non-POD objects. + If the extension does not support relocation at all, set + relocatable = false in its control file, and also set + schema to the name of the intended target schema. This + will prevent use of the SCHEMA option of CREATE + EXTENSION, unless it specifies the same schema named in the control + file. This choice is typically necessary if the extension contains + internal assumptions about schema names that can't be replaced by + uses of @extschema@. The @extschema@ + substitution mechanism is available in this case too, although it is + of limited use since the schema name is determined by the control file. + + + In all cases, the script file will be executed with + initially set to point to the target + schema; that is, CREATE EXTENSION does the equivalent of + this: + +SET LOCAL search_path TO @extschema@; + + This allows the objects created by the script file to go into the target + schema. The script file can change search_path if it wishes, + but that is generally undesirable. search_path is restored + to its previous setting upon completion of CREATE EXTENSION. + + + + The target schema is determined by the schema parameter in + the control file if that is given, otherwise by the SCHEMA + option of CREATE EXTENSION if that is given, otherwise the + current default object creation schema (the first one in the caller's + search_path). When the control file schema + parameter is used, the target schema will be created if it doesn't + already exist, but in the other two cases it must already exist. + + + + If any prerequisite extensions are listed in requires + in the control file, their target schemas are appended to the initial + setting of search_path. This allows their objects to be + visible to the new extension's script file. + + + + Although a non-relocatable extension can contain objects spread across + multiple schemas, it is usually desirable to place all the objects meant + for external use into a single schema, which is considered the extension's + target schema. Such an arrangement works conveniently with the default + setting of search_path during creation of dependent + extensions. + + + + + Extension Configuration Tables + + + Some extensions include configuration tables, which contain data that + might be added or changed by the user after installation of the + extension. Ordinarily, if a table is part of an extension, neither + the table's definition nor its content will be dumped by + pg_dump. But that behavior is undesirable for a + configuration table; any data changes made by the user need to be + included in dumps, or the extension will behave differently after a dump + and reload. + + + + To solve this problem, an extension's script file can mark a table + it has created as a configuration table, which will cause + pg_dump to include the table's contents (not its + definition) in dumps. To do that, call the function + pg_extension_config_dump(regclass, text) after creating the + table, for example + +CREATE TABLE my_config (key text, value text); + +SELECT pg_catalog.pg_extension_config_dump('my_config', ''); + + Any number of tables can be marked this way. + + + + When the second argument of pg_extension_config_dump is + an empty string, the entire contents of the table are dumped by + pg_dump. This is usually only correct if the table + is initially empty as created by the extension script. If there is + a mixture of initial data and user-provided data in the table, + the second argument of pg_extension_config_dump provides + a WHERE condition that selects the data to be dumped. + For example, you might do + +CREATE TABLE my_config (key text, value text, standard_entry boolean); + +SELECT pg_catalog.pg_extension_config_dump('my_config', 'WHERE NOT standard_entry'); + + and then make sure that standard_entry is true only + in the rows created by the extension's script. + + + + More complicated situations, such as initially-provided rows that might + be modified by users, can be handled by creating triggers on the + configuration table to ensure that modified rows are marked correctly. + + + + + Extension Example + + + Here is a complete example of an SQL-only + extension, a two-element composite type that can store any type of value + in its slots, which are named k and v. Non-text + values are automatically coerced to text for storage. + + + + The script file pair.sql looks like this: + + (LEFTARG = text, RIGHTARG = anyelement, PROCEDURE = pair); +CREATE OPERATOR ~> (LEFTARG = anyelement, RIGHTARG = text, PROCEDURE = pair); +CREATE OPERATOR ~> (LEFTARG = anyelement, RIGHTARG = anyelement, PROCEDURE = pair); +CREATE OPERATOR ~> (LEFTARG = text, RIGHTARG = text, PROCEDURE = pair); +]]> + + + + + The control file pair.control looks like this: + + +# pair extension +comment = 'A key/value pair data type' +version = '0.1.2' +relocatable = true + + + + + While you hardly need a makefile to install these two files into the + correct directory, you could use a Makefile containing this: + + +EXTENSION = pair +DATA = pair.sql + +PG_CONFIG = pg_config +PGXS := $(shell $(PG_CONFIG) --pgxs) +include $(PGXS) + + + This makefile relies on PGXS, which is described + in . The command make install + will then install the control and script files into the correct + directory as reported by pg_config. + + + + Once the files are installed, use the + command to load the objects into + any particular database. + + + + + + Extension Building Infrastructure + + + pgxs + + + + If you are thinking about distributing your + PostgreSQL extension modules, setting up a + portable build system for them can be fairly difficult. Therefore + the PostgreSQL installation provides a build + infrastructure for extensions, called PGXS, so + that simple extension modules can be built simply against an + already installed server. PGXS is mainly intended + for extensions that include C code, although it can be used for + pure-SQL extensions too. Note that PGXS is not + intended to be a universal build system framework that can be used + to build any software interfacing to PostgreSQL; + it simply automates common build rules for simple server extension + modules. For more complicated packages, you might need to write your + own build system. - In summary, it is best to place C++ code behind a wall of - extern C functions that interface to the backend, - and avoid exception, memory, and call stack leakage. + To use the PGXS infrastructure for your extension, + you must write a simple makefile. + In the makefile, you need to set some variables + and finally include the global PGXS makefile. + Here is an example that builds an extension module named + isbn_issn, consisting of a shared library containing + some C code, an extension control file, a SQL script, and a documentation + text file: + +MODULES = isbn_issn +EXTENSION = isbn_issn +DATA_built = isbn_issn.sql +DOCS = README.isbn_issn + +PG_CONFIG = pg_config +PGXS := $(shell $(PG_CONFIG) --pgxs) +include $(PGXS) + + The last three lines should always be the same. Earlier in the + file, you assign variables or add custom + make rules. + + + Set one of these three variables to specify what is built: + + + + MODULES + + + list of shared-library objects to be built from source files with same + stem (do not include library suffixes in this list) + + + + + + MODULE_big + + + a shared library to build from multiple source files + (list object files in OBJS) + + + + + + PROGRAM + + + an executable program to build + (list object files in OBJS) + + + + + + The following variables can also be set: + + + + MODULEDIR + + + subdirectory into which EXTENSION, DATA and DOCS files should be + installed (if not set, default is contrib) + + + + + + EXTENSION + + + extension name(s); for each name you must provide an + extension.control file, + which will be installed into + prefix/share/$MODULEDIR + + + + + + DATA + + + random files to install into prefix/share/$MODULEDIR + + + + + + DATA_built + + + random files to install into + prefix/share/$MODULEDIR, + which need to be built first + + + + + + DATA_TSEARCH + + + random files to install under + prefix/share/tsearch_data + + + + + + DOCS + + + random files to install under + prefix/doc/$MODULEDIR + + + + + + SCRIPTS + + + script files (not binaries) to install into + prefix/bin + + + + + + SCRIPTS_built + + + script files (not binaries) to install into + prefix/bin, + which need to be built first + + + + + + REGRESS + + + list of regression test cases (without suffix), see below + + + + + + EXTRA_CLEAN + + + extra files to remove in make clean + + + + + + PG_CPPFLAGS + + + will be added to CPPFLAGS + + + + + + PG_LIBS + + + will be added to PROGRAM link line + + + + + + SHLIB_LINK + + + will be added to MODULE_big link line + + + + + + PG_CONFIG + + + path to pg_config program for the + PostgreSQL installation to build against + (typically just pg_config to use the first one in your + PATH) + + + + + + + + Put this makefile as Makefile in the directory + which holds your extension. Then you can do + make to compile, and then make + install to install your module. By default, the extension is + compiled and installed for the + PostgreSQL installation that + corresponds to the first pg_config program + found in your PATH. You can use a different installation by + setting PG_CONFIG to point to its + pg_config program, either within the makefile + or on the make command line. + + + + + Changing PG_CONFIG only works when building + against PostgreSQL 8.3 or later. + With older releases it does not work to set it to anything except + pg_config; you must alter your PATH + to select the installation to build against. + + + + + The scripts listed in the REGRESS variable are used for + regression testing of your module, which can be invoked by make + installcheck after doing make install. For this to + work you must have a running PostgreSQL server. + The script files listed in REGRESS must appear in a + subdirectory named sql/ in your extension's directory. + These files must have extension .sql, which must not be + included in the REGRESS list in the makefile. For each + test there should also be a file containing the expected output in a + subdirectory named expected/, with the same stem and + extension .out. make installcheck + executes each test script with psql, and compares the + resulting output to the matching expected file. Any differences will be + written to the file regression.diffs in diff + -c format. Note that trying to run a test that is missing its + expected file will be reported as trouble, so make sure you + have all expected files. + + + + + The easiest way to create the expected files is to create empty files, + then do a test run (which will of course report differences). Inspect + the actual result files found in the results/ + directory, then copy them to expected/ if they match + what you expect from the test. + + + diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml index c44d11ef91b..ba85cae0837 100644 --- a/doc/src/sgml/ref/allfiles.sgml +++ b/doc/src/sgml/ref/allfiles.sgml @@ -11,6 +11,7 @@ Complete list of usable sgml source files in this directory. + @@ -50,6 +51,7 @@ Complete list of usable sgml source files in this directory. + @@ -86,6 +88,7 @@ Complete list of usable sgml source files in this directory. + diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml new file mode 100644 index 00000000000..1b29d274cd6 --- /dev/null +++ b/doc/src/sgml/ref/alter_extension.sgml @@ -0,0 +1,98 @@ + + + + + ALTER EXTENSION + 7 + SQL - Language Statements + + + + ALTER EXTENSION + + change the definition of an extension + + + + + ALTER EXTENSION + + + + +ALTER EXTENSION name SET SCHEMA new_schema + + + + + Description + + + ALTER EXTENSION changes the definition of an existing extension. + Currently there is only one subform: + + + + SET SCHEMA + + + This form moves the extension's objects into another schema. The + extension has to be relocatable for this command to + succeed. See for details. + + + + + + + + + Parameters + + + + + name + + + The name of an installed extension. + + + + + + new_schema + + + The new schema for the extension. + + + + + + + + + Examples + + + To change the schema of the extension hstore + to utils: + +ALTER EXTENSION hstore SET SCHEMA utils; + + + + + + See Also + + + + + + + diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index f1a1605df3c..e1fe0c16f9a 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -31,6 +31,7 @@ COMMENT ON CONVERSION object_name | DATABASE object_name | DOMAIN object_name | + EXTENSION object_name | FOREIGN TABLE object_name | FUNCTION function_name ( [ [ argmode ] [ argname ] argtype [, ...] ] ) | INDEX object_name | diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml new file mode 100644 index 00000000000..961cab3839e --- /dev/null +++ b/doc/src/sgml/ref/create_extension.sgml @@ -0,0 +1,118 @@ + + + + + CREATE EXTENSION + 7 + SQL - Language Statements + + + + CREATE EXTENSION + install an extension + + + + CREATE EXTENSION + + + + +CREATE EXTENSION extension_name + [ WITH ] [ SCHEMA [=] schema ] + + + + + Description + + + CREATE EXTENSION loads a new extension into the current + database. There must not be an extension of the same name already loaded. + + + + Loading an extension essentially amounts to running the extension's script + file. The script will typically create new SQL objects such as + functions, data types, operators and index support methods. + CREATE EXTENSION additionally records the identities + of all the created objects, so that they can be dropped again if + DROP EXTENSION is issued. + + + + For information about writing new extensions, see + . + + + + Only superusers can execute CREATE EXTENSION. + + + + + + Parameters + + + + extension_name + + + The name of the extension to be + installed. PostgreSQL will create the + extension using details from the file + SHAREDIR/contrib/extension.control. + + + + + + schema + + + 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. + + + + + + + + Examples + + + Install the hstore extension into the + current database: + +CREATE EXTENSION hstore; + + + + + + Compatibility + + + CREATE EXTENSION is a PostgreSQL + extension. + + + + + See Also + + + + + + + + diff --git a/doc/src/sgml/ref/drop_extension.sgml b/doc/src/sgml/ref/drop_extension.sgml new file mode 100644 index 00000000000..1e09ec4c7a7 --- /dev/null +++ b/doc/src/sgml/ref/drop_extension.sgml @@ -0,0 +1,121 @@ + + + + + DROP EXTENSION + 7 + SQL - Language Statements + + + + DROP EXTENSION + remove an extension + + + + DROP EXTENSION + + + + +DROP EXTENSION [ IF EXISTS ] extension_name [, ...] [ CASCADE | RESTRICT ] + + + + + Description + + + DROP EXTENSION removes extensions from the database. + Dropping an extension causes its component objects to be dropped as well. + + + + An extension can only be dropped by a superuser. + + + + + Parameters + + + + + IF EXISTS + + + Do not throw an error if the extension does not exist. A notice is issued + in this case. + + + + + + extension_name + + + The name of an installed extension. + + + + + + CASCADE + + + Automatically drop objects that depend on the extension. + + + + + + RESTRICT + + + Refuse to drop the extension if any objects depend on it (other than + its own member objects and other extensions listed in the same + DROP command). This is the default. + + + + + + + + Examples + + + To remove the extension hstore from the current + database: + +DROP EXTENSION hstore; + + This command will fail if any of hstore's objects + are in use in the database, for example if any tables have columns + of the hstore type. Add the CASCADE option to + forcibly remove those dependent objects as well. + + + + + Compatibility + + + DROP EXTENSION is a PostgreSQL + extension. + + + + + See Also + + + + + + + + diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index eacae71cdc7..cdf1abfa956 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -1357,7 +1357,6 @@ testdb=> - \du[+] [ pattern ] @@ -1371,6 +1370,19 @@ testdb=> + + \dx[+] [ pattern ] + + + Lists installed extensions. + If pattern + is specified, only those extensions whose names match the pattern + are listed. + If the form \dx+ is used, all the objects belonging + to each matching extension are listed. + + + \edit (or \e) filename line_number diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index 6ee8e5bcff8..47cd01f58e2 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -39,6 +39,7 @@ &alterDatabase; &alterDefaultPrivileges; &alterDomain; + &alterExtension; &alterForeignDataWrapper; &alterForeignTable; &alterFunction; @@ -78,6 +79,7 @@ &createConversion; &createDatabase; &createDomain; + &createExtension; &createForeignDataWrapper; &createForeignTable; &createFunction; @@ -114,6 +116,7 @@ &dropConversion; &dropDatabase; &dropDomain; + &dropExtension; &dropForeignDataWrapper; &dropForeignTable; &dropFunction; diff --git a/doc/src/sgml/release-9.0.sgml b/doc/src/sgml/release-9.0.sgml index 2288f1b0e64..4902c058a96 100644 --- a/doc/src/sgml/release-9.0.sgml +++ b/doc/src/sgml/release-9.0.sgml @@ -3520,9 +3520,8 @@ if TG_OP = 'INSERT' and NEW.col1 = ... then - Add data and documentation installation location control to PGXS Makefiles - (Mark Cave-Ayland) + Add data and documentation installation location control to + PGXS Makefiles (Mark Cave-Ayland) diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 4ad50ec0cb5..4f2c23fab7a 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -2392,273 +2392,6 @@ concat_text(PG_FUNCTION_ARGS) &dfunc; - - Extension Building Infrastructure - - - pgxs - - - - If you are thinking about distributing your - PostgreSQL extension modules, setting up a - portable build system for them can be fairly difficult. Therefore - the PostgreSQL installation provides a build - infrastructure for extensions, called PGXS, so - that simple extension modules can be built simply against an - already installed server. Note that this infrastructure is not - intended to be a universal build system framework that can be used - to build all software interfacing to PostgreSQL; - it simply automates common build rules for simple server extension - modules. For more complicated packages, you need to write your - own build system. - - - - To use the infrastructure for your extension, you must write a - simple makefile. In that makefile, you need to set some variables - and finally include the global PGXS makefile. - Here is an example that builds an extension module named - isbn_issn consisting of a shared library, an - SQL script, and a documentation text file: - -MODULES = isbn_issn -DATA_built = isbn_issn.sql -DOCS = README.isbn_issn - -PG_CONFIG = pg_config -PGXS := $(shell $(PG_CONFIG) --pgxs) -include $(PGXS) - - The last three lines should always be the same. Earlier in the - file, you assign variables or add custom - make rules. - - - - Set one of these three variables to specify what is built: - - - - MODULES - - - list of shared objects to be built from source files with same - stem (do not include suffix in this list) - - - - - - MODULE_big - - - a shared object to build from multiple source files - (list object files in OBJS) - - - - - - PROGRAM - - - a binary program to build - (list object files in OBJS) - - - - - - The following variables can also be set: - - - - MODULEDIR - - - subdirectory into which DATA and DOCS files should be - installed (if not set, default is contrib) - - - - - - DATA - - - random files to install into prefix/share/$MODULEDIR - - - - - - DATA_built - - - random files to install into - prefix/share/$MODULEDIR, - which need to be built first - - - - - - DATA_TSEARCH - - - random files to install under - prefix/share/tsearch_data - - - - - - DOCS - - - random files to install under - prefix/doc/$MODULEDIR - - - - - - SCRIPTS - - - script files (not binaries) to install into - prefix/bin - - - - - - SCRIPTS_built - - - script files (not binaries) to install into - prefix/bin, - which need to be built first - - - - - - REGRESS - - - list of regression test cases (without suffix), see below - - - - - - EXTRA_CLEAN - - - extra files to remove in make clean - - - - - - PG_CPPFLAGS - - - will be added to CPPFLAGS - - - - - - PG_LIBS - - - will be added to PROGRAM link line - - - - - - SHLIB_LINK - - - will be added to MODULE_big link line - - - - - - PG_CONFIG - - - path to pg_config program for the - PostgreSQL installation to build against - (typically just pg_config to use the first one in your - PATH) - - - - - - - - Put this makefile as Makefile in the directory - which holds your extension. Then you can do - make to compile, and later make - install to install your module. By default, the extension is - compiled and installed for the - PostgreSQL installation that - corresponds to the first pg_config program - found in your path. You can use a different installation by - setting PG_CONFIG to point to its - pg_config program, either within the makefile - or on the make command line. - - - - - Changing PG_CONFIG only works when building - against PostgreSQL 8.3 or later. - With older releases it does not work to set it to anything except - pg_config; you must alter your PATH - to select the installation to build against. - - - - - The scripts listed in the REGRESS variable are used for - regression testing of your module, just like make - installcheck is used for the main - PostgreSQL server. For this to work you need - to have a subdirectory named sql/ in your extension's - directory, within which you put one file for each group of tests you want - to run. The files should have extension .sql, which - should not be included in the REGRESS list in the - makefile. For each test there should be a file containing the expected - result in a subdirectory named expected/, with extension - .out. The tests are run by executing make - installcheck, and the resulting output will be compared to the - expected files. The differences will be written to the file - regression.diffs in diff -c format. - Note that trying to run a test which is missing the expected file will be - reported as trouble, so make sure you have all expected - files. - - - - - The easiest way of creating the expected files is creating empty files, - then carefully inspecting the result files after a test run (to be found - in the results/ directory), and copying them to - expected/ if they match what you want from the test. - - - - - - Composite-type Arguments @@ -3385,4 +3118,68 @@ if (!ptr) + + + Using C++ for Extensibility + + + C++ + + + + Although the PostgreSQL backend is written in + C, it is possible to write extensions in C++ if these guidelines are + followed: + + + + + All functions accessed by the backend must present a C interface + to the backend; these C functions can then call C++ functions. + For example, extern C linkage is required for + backend-accessed functions. This is also necessary for any + functions that are passed as pointers between the backend and + C++ code. + + + + + Free memory using the appropriate deallocation method. For example, + most backend memory is allocated using palloc(), so use + pfree() to free it. Using C++ + delete in such cases will fail. + + + + + Prevent exceptions from propagating into the C code (use a catch-all + block at the top level of all extern C functions). This + is necessary even if the C++ code does not explicitly throw any + exceptions, because events like out-of-memory can still throw + exceptions. Any exceptions must be caught and appropriate errors + passed back to the C interface. If possible, compile C++ with + + + + + If calling backend functions from C++ code, be sure that the + C++ call stack contains only plain old data structures + (POD). This is necessary because backend errors + generate a distant longjmp() that does not properly + unroll a C++ call stack with non-POD objects. + + + + + + + In summary, it is best to place C++ code behind a wall of + extern C functions that interface to the backend, + and avoid exception, memory, and call stack leakage. + + + -- cgit v1.2.3