diff options
Diffstat (limited to 'doc/src/sgml/man7')
185 files changed, 40472 insertions, 0 deletions
diff --git a/doc/src/sgml/man7/ABORT.7 b/doc/src/sgml/man7/ABORT.7 new file mode 100644 index 0000000..02b4299 --- /dev/null +++ b/doc/src/sgml/man7/ABORT.7 @@ -0,0 +1,90 @@ +'\" t +.\" Title: ABORT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ABORT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ABORT \- abort the current transaction +.SH "SYNOPSIS" +.sp +.nf +ABORT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] +.fi +.SH "DESCRIPTION" +.PP +\fBABORT\fR +rolls back the current transaction and causes all the updates made by the transaction to be discarded\&. This command is identical in behavior to the standard +SQL +command +\fBROLLBACK\fR, and is present only for historical reasons\&. +.SH "PARAMETERS" +.PP +WORK +.br +TRANSACTION +.RS 4 +Optional key words\&. They have no effect\&. +.RE +.PP +AND CHAIN +.RS 4 +If +AND CHAIN +is specified, a new transaction is immediately started with the same transaction characteristics (see +\fBSET TRANSACTION\fR) as the just finished one\&. Otherwise, no new transaction is started\&. +.RE +.SH "NOTES" +.PP +Use +\fBCOMMIT\fR +to successfully terminate a transaction\&. +.PP +Issuing +\fBABORT\fR +outside of a transaction block emits a warning and otherwise has no effect\&. +.SH "EXAMPLES" +.PP +To abort all changes: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ABORT; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command is a +PostgreSQL +extension present for historical reasons\&. +\fBROLLBACK\fR +is the equivalent standard SQL command\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), \fBROLLBACK\fR(7) diff --git a/doc/src/sgml/man7/ALTER_AGGREGATE.7 b/doc/src/sgml/man7/ALTER_AGGREGATE.7 new file mode 100644 index 0000000..377bbc1 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_AGGREGATE.7 @@ -0,0 +1,187 @@ +'\" t +.\" Title: ALTER AGGREGATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER AGGREGATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_AGGREGATE \- change the definition of an aggregate function +.SH "SYNOPSIS" +.sp +.nf +ALTER AGGREGATE \fIname\fR ( \fIaggregate_signature\fR ) RENAME TO \fInew_name\fR +ALTER AGGREGATE \fIname\fR ( \fIaggregate_signature\fR ) + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER AGGREGATE \fIname\fR ( \fIaggregate_signature\fR ) SET SCHEMA \fInew_schema\fR + +where \fIaggregate_signature\fR is: + +* | +[ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] | +[ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER AGGREGATE\fR +changes the definition of an aggregate function\&. +.PP +You must own the aggregate function to use +\fBALTER AGGREGATE\fR\&. To change the schema of an aggregate function, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the aggregate function\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the aggregate function\&. However, a superuser can alter ownership of any aggregate function anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing aggregate function\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN +or +VARIADIC\&. If omitted, the default is +IN\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Note that +\fBALTER AGGREGATE\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the aggregate function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +An input data type on which the aggregate function operates\&. To reference a zero\-argument aggregate function, write +* +in place of the list of argument specifications\&. To reference an ordered\-set aggregate function, write +ORDER BY +between the direct and aggregated argument specifications\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the aggregate function\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the aggregate function\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the aggregate function\&. +.RE +.SH "NOTES" +.PP +The recommended syntax for referencing an ordered\-set aggregate is to write +ORDER BY +between the direct and aggregated argument specifications, in the same style as in +\fBCREATE AGGREGATE\fR\&. However, it will also work to omit +ORDER BY +and just run the direct and aggregated argument specifications into a single list\&. In this abbreviated form, if +VARIADIC "any" +was used in both the direct and aggregated argument lists, write +VARIADIC "any" +only once\&. +.SH "EXAMPLES" +.PP +To rename the aggregate function +myavg +for type +integer +to +my_average: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER AGGREGATE myavg(integer) RENAME TO my_average; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the aggregate function +myavg +for type +integer +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER AGGREGATE myavg(integer) OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.PP +To move the ordered\-set aggregate +mypercentile +with direct argument of type +float8 +and aggregated argument of type +integer +into schema +myschema: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER AGGREGATE mypercentile(float8 ORDER BY integer) SET SCHEMA myschema; +.fi +.if n \{\ +.RE +.\} +.sp +This will work too: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER AGGREGATE mypercentile(float8, integer) SET SCHEMA myschema; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER AGGREGATE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE AGGREGATE (\fBCREATE_AGGREGATE\fR(7)), DROP AGGREGATE (\fBDROP_AGGREGATE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_COLLATION.7 b/doc/src/sgml/man7/ALTER_COLLATION.7 new file mode 100644 index 0000000..131fd69 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_COLLATION.7 @@ -0,0 +1,178 @@ +'\" t +.\" Title: ALTER COLLATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER COLLATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_COLLATION \- change the definition of a collation +.SH "SYNOPSIS" +.sp +.nf +ALTER COLLATION \fIname\fR REFRESH VERSION + +ALTER COLLATION \fIname\fR RENAME TO \fInew_name\fR +ALTER COLLATION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER COLLATION \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER COLLATION\fR +changes the definition of a collation\&. +.PP +You must own the collation to use +\fBALTER COLLATION\fR\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the collation\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the collation\&. However, a superuser can alter ownership of any collation anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing collation\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the collation\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the collation\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the collation\&. +.RE +.PP +REFRESH VERSION +.RS 4 +Update the collation\*(Aqs version\&. See +Notes +below\&. +.RE +.SH "NOTES" +.PP +When a collation object is created, the provider\-specific version of the collation is recorded in the system catalog\&. When the collation is used, the current version is checked against the recorded version, and a warning is issued when there is a mismatch, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +WARNING: collation "xx\-x\-icu" has version mismatch +DETAIL: The collation in the database was created using version 1\&.2\&.3\&.4, but the operating system provides version 2\&.3\&.4\&.5\&. +HINT: Rebuild all objects affected by this collation and run ALTER COLLATION pg_catalog\&."xx\-x\-icu" REFRESH VERSION, or build PostgreSQL with the right library version\&. +.fi +.if n \{\ +.RE +.\} +.sp +A change in collation definitions can lead to corrupt indexes and other problems because the database system relies on stored objects having a certain sort order\&. Generally, this should be avoided, but it can happen in legitimate circumstances, such as when upgrading the operating system to a new major version or when using +\fBpg_upgrade\fR +to upgrade to server binaries linked with a newer version of ICU\&. When this happens, all objects depending on the collation should be rebuilt, for example, using +\fBREINDEX\fR\&. When that is done, the collation version can be refreshed using the command +ALTER COLLATION \&.\&.\&. REFRESH VERSION\&. This will update the system catalog to record the current collation version and will make the warning go away\&. Note that this does not actually check whether all affected objects have been rebuilt correctly\&. +.PP +When using collations provided by +libc, version information is recorded on systems using the GNU C library (most Linux systems), FreeBSD and Windows\&. When using collations provided by ICU, the version information is provided by the ICU library and is available on all platforms\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +When using the GNU C library for collations, the C library\*(Aqs version is used as a proxy for the collation version\&. Many Linux distributions change collation definitions only when upgrading the C library, but this approach is imperfect as maintainers are free to back\-port newer collation definitions to older C library releases\&. +.PP +When using Windows for collations, version information is only available for collations defined with BCP 47 language tags such as +en\-US\&. +.sp .5v +.RE +.PP +For the database default collation, there is an analogous command +ALTER DATABASE \&.\&.\&. REFRESH COLLATION VERSION\&. +.PP +The following query can be used to identify all collations in the current database that need to be refreshed and the objects that depend on them: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT pg_describe_object(refclassid, refobjid, refobjsubid) AS "Collation", + pg_describe_object(classid, objid, objsubid) AS "Object" + FROM pg_depend d JOIN pg_collation c + ON refclassid = \*(Aqpg_collation\*(Aq::regclass AND refobjid = c\&.oid + WHERE c\&.collversion <> pg_collation_actual_version(c\&.oid) + ORDER BY 1, 2; +.fi +.if n \{\ +.RE +.\} +.SH "EXAMPLES" +.PP +To rename the collation +de_DE +to +german: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER COLLATION "de_DE" RENAME TO german; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the collation +en_US +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER COLLATION "en_US" OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER COLLATION\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE COLLATION (\fBCREATE_COLLATION\fR(7)), DROP COLLATION (\fBDROP_COLLATION\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_CONVERSION.7 b/doc/src/sgml/man7/ALTER_CONVERSION.7 new file mode 100644 index 0000000..630bc25 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_CONVERSION.7 @@ -0,0 +1,106 @@ +'\" t +.\" Title: ALTER CONVERSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER CONVERSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_CONVERSION \- change the definition of a conversion +.SH "SYNOPSIS" +.sp +.nf +ALTER CONVERSION \fIname\fR RENAME TO \fInew_name\fR +ALTER CONVERSION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER CONVERSION \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER CONVERSION\fR +changes the definition of a conversion\&. +.PP +You must own the conversion to use +\fBALTER CONVERSION\fR\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the conversion\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the conversion\&. However, a superuser can alter ownership of any conversion anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing conversion\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the conversion\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the conversion\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the conversion\&. +.RE +.SH "EXAMPLES" +.PP +To rename the conversion +iso_8859_1_to_utf8 +to +latin1_to_unicode: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER CONVERSION iso_8859_1_to_utf8 RENAME TO latin1_to_unicode; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the conversion +iso_8859_1_to_utf8 +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER CONVERSION iso_8859_1_to_utf8 OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER CONVERSION\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE CONVERSION (\fBCREATE_CONVERSION\fR(7)), DROP CONVERSION (\fBDROP_CONVERSION\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_DATABASE.7 b/doc/src/sgml/man7/ALTER_DATABASE.7 new file mode 100644 index 0000000..c9e2f76 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_DATABASE.7 @@ -0,0 +1,176 @@ +'\" t +.\" Title: ALTER DATABASE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER DATABASE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_DATABASE \- change a database +.SH "SYNOPSIS" +.sp +.nf +ALTER DATABASE \fIname\fR [ [ WITH ] \fIoption\fR [ \&.\&.\&. ] ] + +where \fIoption\fR can be: + + ALLOW_CONNECTIONS \fIallowconn\fR + CONNECTION LIMIT \fIconnlimit\fR + IS_TEMPLATE \fIistemplate\fR + +ALTER DATABASE \fIname\fR RENAME TO \fInew_name\fR + +ALTER DATABASE \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } + +ALTER DATABASE \fIname\fR SET TABLESPACE \fInew_tablespace\fR + +ALTER DATABASE \fIname\fR REFRESH COLLATION VERSION + +ALTER DATABASE \fIname\fR SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT } +ALTER DATABASE \fIname\fR SET \fIconfiguration_parameter\fR FROM CURRENT +ALTER DATABASE \fIname\fR RESET \fIconfiguration_parameter\fR +ALTER DATABASE \fIname\fR RESET ALL +.fi +.SH "DESCRIPTION" +.PP +\fBALTER DATABASE\fR +changes the attributes of a database\&. +.PP +The first form changes certain per\-database settings\&. (See below for details\&.) Only the database owner or a superuser can change these settings\&. +.PP +The second form changes the name of the database\&. Only the database owner or a superuser can rename a database; non\-superuser owners must also have the +CREATEDB +privilege\&. The current database cannot be renamed\&. (Connect to a different database if you need to do that\&.) +.PP +The third form changes the owner of the database\&. To alter the owner, you must own the database and also be a direct or indirect member of the new owning role, and you must have the +CREATEDB +privilege\&. (Note that superusers have all these privileges automatically\&.) +.PP +The fourth form changes the default tablespace of the database\&. Only the database owner or a superuser can do this; you must also have create privilege for the new tablespace\&. This command physically moves any tables or indexes in the database\*(Aqs old default tablespace to the new tablespace\&. The new default tablespace must be empty for this database, and no one can be connected to the database\&. Tables and indexes in non\-default tablespaces are unaffected\&. +.PP +The remaining forms change the session default for a run\-time configuration variable for a +PostgreSQL +database\&. Whenever a new session is subsequently started in that database, the specified value becomes the session default value\&. The database\-specific default overrides whatever setting is present in +postgresql\&.conf +or has been received from the +\fBpostgres\fR +command line\&. Only the database owner or a superuser can change the session defaults for a database\&. Certain variables cannot be set this way, or can only be set by a superuser\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the database whose attributes are to be altered\&. +.RE +.PP +\fIallowconn\fR +.RS 4 +If false then no one can connect to this database\&. +.RE +.PP +\fIconnlimit\fR +.RS 4 +How many concurrent connections can be made to this database\&. \-1 means no limit\&. +.RE +.PP +\fIistemplate\fR +.RS 4 +If true, then this database can be cloned by any user with +CREATEDB +privileges; if false, then only superusers or the owner of the database can clone it\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the database\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the database\&. +.RE +.PP +\fInew_tablespace\fR +.RS 4 +The new default tablespace of the database\&. +.sp +This form of the command cannot be executed inside a transaction block\&. +.RE +.PP +REFRESH COLLATION VERSION +.RS 4 +Update the database collation version\&. See +Notes +for background\&. +.RE +.PP +\fIconfiguration_parameter\fR +.br +\fIvalue\fR +.RS 4 +Set this database\*(Aqs session default for the specified configuration parameter to the given value\&. If +\fIvalue\fR +is +DEFAULT +or, equivalently, +RESET +is used, the database\-specific setting is removed, so the system\-wide default setting will be inherited in new sessions\&. Use +RESET ALL +to clear all database\-specific settings\&. +SET FROM CURRENT +saves the session\*(Aqs current value of the parameter as the database\-specific value\&. +.sp +See +\fBSET\fR(7) +and +Chapter\ \&20 +for more information about allowed parameter names and values\&. +.RE +.SH "NOTES" +.PP +It is also possible to tie a session default to a specific role rather than to a database; see +ALTER ROLE (\fBALTER_ROLE\fR(7))\&. Role\-specific settings override database\-specific ones if there is a conflict\&. +.SH "EXAMPLES" +.PP +To disable index scans by default in the database +test: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DATABASE test SET enable_indexscan TO off; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBALTER DATABASE\fR +statement is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE DATABASE (\fBCREATE_DATABASE\fR(7)), DROP DATABASE (\fBDROP_DATABASE\fR(7)), \fBSET\fR(7), CREATE TABLESPACE (\fBCREATE_TABLESPACE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_DEFAULT_PRIVILEGES.7 b/doc/src/sgml/man7/ALTER_DEFAULT_PRIVILEGES.7 new file mode 100644 index 0000000..7a09b50 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_DEFAULT_PRIVILEGES.7 @@ -0,0 +1,231 @@ +'\" t +.\" Title: ALTER DEFAULT PRIVILEGES +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER DEFAULT PRIVILEGES" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_DEFAULT_PRIVILEGES \- define default access privileges +.SH "SYNOPSIS" +.sp +.nf +ALTER DEFAULT PRIVILEGES + [ FOR { ROLE | USER } \fItarget_role\fR [, \&.\&.\&.] ] + [ IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] ] + \fIabbreviated_grant_or_revoke\fR + +where \fIabbreviated_grant_or_revoke\fR is one of: + +GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON TABLES + TO { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] [ WITH GRANT OPTION ] + +GRANT { { USAGE | SELECT | UPDATE } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON SEQUENCES + TO { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] [ WITH GRANT OPTION ] + +GRANT { EXECUTE | ALL [ PRIVILEGES ] } + ON { FUNCTIONS | ROUTINES } + TO { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] [ WITH GRANT OPTION ] + +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON TYPES + TO { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] [ WITH GRANT OPTION ] + +GRANT { USAGE | CREATE | ALL [ PRIVILEGES ] } + ON SCHEMAS + TO { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] [ WITH GRANT OPTION ] + +REVOKE [ GRANT OPTION FOR ] + { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON TABLES + FROM { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { USAGE | SELECT | UPDATE } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON SEQUENCES + FROM { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { EXECUTE | ALL [ PRIVILEGES ] } + ON { FUNCTIONS | ROUTINES } + FROM { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON TYPES + FROM { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | CREATE | ALL [ PRIVILEGES ] } + ON SCHEMAS + FROM { [ GROUP ] \fIrole_name\fR | PUBLIC } [, \&.\&.\&.] + [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER DEFAULT PRIVILEGES\fR +allows you to set the privileges that will be applied to objects created in the future\&. (It does not affect privileges assigned to already\-existing objects\&.) Currently, only the privileges for schemas, tables (including views and foreign tables), sequences, functions, and types (including domains) can be altered\&. For this command, functions include aggregates and procedures\&. The words +FUNCTIONS +and +ROUTINES +are equivalent in this command\&. (ROUTINES +is preferred going forward as the standard term for functions and procedures taken together\&. In earlier PostgreSQL releases, only the word +FUNCTIONS +was allowed\&. It is not possible to set default privileges for functions and procedures separately\&.) +.PP +You can change default privileges only for objects that will be created by yourself or by roles that you are a member of\&. The privileges can be set globally (i\&.e\&., for all objects created in the current database), or just for objects created in specified schemas\&. +.PP +As explained in +Section\ \&5.7, the default privileges for any object type normally grant all grantable permissions to the object owner, and may grant some privileges to +PUBLIC +as well\&. However, this behavior can be changed by altering the global default privileges with +\fBALTER DEFAULT PRIVILEGES\fR\&. +.PP +Default privileges that are specified per\-schema are added to whatever the global default privileges are for the particular object type\&. This means you cannot revoke privileges per\-schema if they are granted globally (either by default, or according to a previous +\fBALTER DEFAULT PRIVILEGES\fR +command that did not specify a schema)\&. Per\-schema +REVOKE +is only useful to reverse the effects of a previous per\-schema +GRANT\&. +.SS "Parameters" +.PP +\fItarget_role\fR +.RS 4 +The name of an existing role of which the current role is a member\&. Default access privileges are not inherited, so member roles must use +\fBSET ROLE\fR +to access these privileges, or +\fBALTER DEFAULT PRIVILEGES\fR +must be run for each member role\&. If +FOR ROLE +is omitted, the current role is assumed\&. +.RE +.PP +\fIschema_name\fR +.RS 4 +The name of an existing schema\&. If specified, the default privileges are altered for objects later created in that schema\&. If +IN SCHEMA +is omitted, the global default privileges are altered\&. +IN SCHEMA +is not allowed when setting privileges for schemas, since schemas can\*(Aqt be nested\&. +.RE +.PP +\fIrole_name\fR +.RS 4 +The name of an existing role to grant or revoke privileges for\&. This parameter, and all the other parameters in +\fIabbreviated_grant_or_revoke\fR, act as described under +\fBGRANT\fR(7) +or +\fBREVOKE\fR(7), except that one is setting permissions for a whole class of objects rather than specific named objects\&. +.RE +.SH "NOTES" +.PP +Use +\fBpsql\fR(1)\*(Aqs +\fB\eddp\fR +command to obtain information about existing assignments of default privileges\&. The meaning of the privilege display is the same as explained for +\fB\edp\fR +in +Section\ \&5.7\&. +.PP +If you wish to drop a role for which the default privileges have been altered, it is necessary to reverse the changes in its default privileges or use +\fBDROP OWNED BY\fR +to get rid of the default privileges entry for the role\&. +.SH "EXAMPLES" +.PP +Grant SELECT privilege to everyone for all tables (and views) you subsequently create in schema +myschema, and allow role +webuser +to INSERT into them too: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT SELECT ON TABLES TO PUBLIC; +ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT INSERT ON TABLES TO webuser; +.fi +.if n \{\ +.RE +.\} +.PP +Undo the above, so that subsequently\-created tables won\*(Aqt have any more permissions than normal: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE SELECT ON TABLES FROM PUBLIC; +ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLES FROM webuser; +.fi +.if n \{\ +.RE +.\} +.PP +Remove the public EXECUTE permission that is normally granted on functions, for all functions subsequently created by role +admin: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC; +.fi +.if n \{\ +.RE +.\} +.sp +Note however that you +\fIcannot\fR +accomplish that effect with a command limited to a single schema\&. This command has no effect, unless it is undoing a matching +GRANT: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC; +.fi +.if n \{\ +.RE +.\} +.sp +That\*(Aqs because per\-schema default privileges can only add privileges to the global setting, not remove privileges granted by it\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER DEFAULT PRIVILEGES\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBGRANT\fR(7), \fBREVOKE\fR(7) diff --git a/doc/src/sgml/man7/ALTER_DOMAIN.7 b/doc/src/sgml/man7/ALTER_DOMAIN.7 new file mode 100644 index 0000000..9e62624 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_DOMAIN.7 @@ -0,0 +1,293 @@ +'\" t +.\" Title: ALTER DOMAIN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER DOMAIN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_DOMAIN \- change the definition of a domain +.SH "SYNOPSIS" +.sp +.nf +ALTER DOMAIN \fIname\fR + { SET DEFAULT \fIexpression\fR | DROP DEFAULT } +ALTER DOMAIN \fIname\fR + { SET | DROP } NOT NULL +ALTER DOMAIN \fIname\fR + ADD \fIdomain_constraint\fR [ NOT VALID ] +ALTER DOMAIN \fIname\fR + DROP CONSTRAINT [ IF EXISTS ] \fIconstraint_name\fR [ RESTRICT | CASCADE ] +ALTER DOMAIN \fIname\fR + RENAME CONSTRAINT \fIconstraint_name\fR TO \fInew_constraint_name\fR +ALTER DOMAIN \fIname\fR + VALIDATE CONSTRAINT \fIconstraint_name\fR +ALTER DOMAIN \fIname\fR + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER DOMAIN \fIname\fR + RENAME TO \fInew_name\fR +ALTER DOMAIN \fIname\fR + SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER DOMAIN\fR +changes the definition of an existing domain\&. There are several sub\-forms: +.PP +SET/DROP DEFAULT +.RS 4 +These forms set or remove the default value for a domain\&. Note that defaults only apply to subsequent +\fBINSERT\fR +commands; they do not affect rows already in a table using the domain\&. +.RE +.PP +SET/DROP NOT NULL +.RS 4 +These forms change whether a domain is marked to allow NULL values or to reject NULL values\&. You can only +SET NOT NULL +when the columns using the domain contain no null values\&. +.RE +.PP +ADD \fIdomain_constraint\fR [ NOT VALID ] +.RS 4 +This form adds a new constraint to a domain using the same syntax as +\fBCREATE DOMAIN\fR\&. When a new constraint is added to a domain, all columns using that domain will be checked against the newly added constraint\&. These checks can be suppressed by adding the new constraint using the +NOT VALID +option; the constraint can later be made valid using +\fBALTER DOMAIN \&.\&.\&. VALIDATE CONSTRAINT\fR\&. Newly inserted or updated rows are always checked against all constraints, even those marked +NOT VALID\&. +NOT VALID +is only accepted for +CHECK +constraints\&. +.RE +.PP +DROP CONSTRAINT [ IF EXISTS ] +.RS 4 +This form drops constraints on a domain\&. If +IF EXISTS +is specified and the constraint does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +RENAME CONSTRAINT +.RS 4 +This form changes the name of a constraint on a domain\&. +.RE +.PP +VALIDATE CONSTRAINT +.RS 4 +This form validates a constraint previously added as +NOT VALID, that is, it verifies that all values in table columns of the domain type satisfy the specified constraint\&. +.RE +.PP +OWNER +.RS 4 +This form changes the owner of the domain to the specified user\&. +.RE +.PP +RENAME +.RS 4 +This form changes the name of the domain\&. +.RE +.PP +SET SCHEMA +.RS 4 +This form changes the schema of the domain\&. Any constraints associated with the domain are moved into the new schema as well\&. +.RE +.PP +You must own the domain to use +\fBALTER DOMAIN\fR\&. To change the schema of a domain, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the domain\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the domain\&. However, a superuser can alter ownership of any domain anyway\&.) +.SH "PARAMETERS" +.PP +.PP +\fIname\fR +.RS 4 +The name (possibly schema\-qualified) of an existing domain to alter\&. +.RE +.PP +\fIdomain_constraint\fR +.RS 4 +New domain constraint for the domain\&. +.RE +.PP +\fIconstraint_name\fR +.RS 4 +Name of an existing constraint to drop or rename\&. +.RE +.PP +NOT VALID +.RS 4 +Do not verify existing stored data for constraint validity\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the constraint, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the constraint if there are any dependent objects\&. This is the default behavior\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the domain\&. +.RE +.PP +\fInew_constraint_name\fR +.RS 4 +The new name for the constraint\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the domain\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the domain\&. +.RE +.SH "NOTES" +.PP +Although +\fBALTER DOMAIN ADD CONSTRAINT\fR +attempts to verify that existing stored data satisfies the new constraint, this check is not bulletproof, because the command cannot +\(lqsee\(rq +table rows that are newly inserted or updated and not yet committed\&. If there is a hazard that concurrent operations might insert bad data, the way to proceed is to add the constraint using the +NOT VALID +option, commit that command, wait until all transactions started before that commit have finished, and then issue +\fBALTER DOMAIN VALIDATE CONSTRAINT\fR +to search for data violating the constraint\&. This method is reliable because once the constraint is committed, all new transactions are guaranteed to enforce it against new values of the domain type\&. +.PP +Currently, +\fBALTER DOMAIN ADD CONSTRAINT\fR, +\fBALTER DOMAIN VALIDATE CONSTRAINT\fR, and +\fBALTER DOMAIN SET NOT NULL\fR +will fail if the named domain or any derived domain is used within a container\-type column (a composite, array, or range column) in any table in the database\&. They should eventually be improved to be able to verify the new constraint for such nested values\&. +.SH "EXAMPLES" +.PP +To add a +NOT NULL +constraint to a domain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DOMAIN zipcode SET NOT NULL; +.fi +.if n \{\ +.RE +.\} +.sp +To remove a +NOT NULL +constraint from a domain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DOMAIN zipcode DROP NOT NULL; +.fi +.if n \{\ +.RE +.\} +.PP +To add a check constraint to a domain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5); +.fi +.if n \{\ +.RE +.\} +.PP +To remove a check constraint from a domain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DOMAIN zipcode DROP CONSTRAINT zipchk; +.fi +.if n \{\ +.RE +.\} +.PP +To rename a check constraint on a domain: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DOMAIN zipcode RENAME CONSTRAINT zipchk TO zip_check; +.fi +.if n \{\ +.RE +.\} +.PP +To move the domain into a different schema: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER DOMAIN zipcode SET SCHEMA customers; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER DOMAIN\fR +conforms to the +SQL +standard, except for the +OWNER, +RENAME, +SET SCHEMA, and +VALIDATE CONSTRAINT +variants, which are +PostgreSQL +extensions\&. The +NOT VALID +clause of the +ADD CONSTRAINT +variant is also a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE DOMAIN (\fBCREATE_DOMAIN\fR(7)), DROP DOMAIN (\fBDROP_DOMAIN\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_EVENT_TRIGGER.7 b/doc/src/sgml/man7/ALTER_EVENT_TRIGGER.7 new file mode 100644 index 0000000..d06dcd7 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_EVENT_TRIGGER.7 @@ -0,0 +1,74 @@ +'\" t +.\" Title: ALTER EVENT TRIGGER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER EVENT TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_EVENT_TRIGGER \- change the definition of an event trigger +.SH "SYNOPSIS" +.sp +.nf +ALTER EVENT TRIGGER \fIname\fR DISABLE +ALTER EVENT TRIGGER \fIname\fR ENABLE [ REPLICA | ALWAYS ] +ALTER EVENT TRIGGER \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER EVENT TRIGGER \fIname\fR RENAME TO \fInew_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER EVENT TRIGGER\fR +changes properties of an existing event trigger\&. +.PP +You must be superuser to alter an event trigger\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing trigger to alter\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the event trigger\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the event trigger\&. +.RE +.PP +DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER +.RS 4 +These forms configure the firing of event triggers\&. A disabled trigger is still known to the system, but is not executed when its triggering event occurs\&. See also +session_replication_role\&. +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER EVENT TRIGGER\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE EVENT TRIGGER (\fBCREATE_EVENT_TRIGGER\fR(7)), DROP EVENT TRIGGER (\fBDROP_EVENT_TRIGGER\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_EXTENSION.7 b/doc/src/sgml/man7/ALTER_EXTENSION.7 new file mode 100644 index 0000000..9c12bc1 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_EXTENSION.7 @@ -0,0 +1,260 @@ +'\" t +.\" Title: ALTER EXTENSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER EXTENSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_EXTENSION \- change the definition of an extension +.SH "SYNOPSIS" +.sp +.nf +ALTER EXTENSION \fIname\fR UPDATE [ TO \fInew_version\fR ] +ALTER EXTENSION \fIname\fR SET SCHEMA \fInew_schema\fR +ALTER EXTENSION \fIname\fR ADD \fImember_object\fR +ALTER EXTENSION \fIname\fR DROP \fImember_object\fR + +where \fImember_object\fR is: + + ACCESS METHOD \fIobject_name\fR | + AGGREGATE \fIaggregate_name\fR ( \fIaggregate_signature\fR ) | + CAST (\fIsource_type\fR AS \fItarget_type\fR) | + COLLATION \fIobject_name\fR | + CONVERSION \fIobject_name\fR | + DOMAIN \fIobject_name\fR | + EVENT TRIGGER \fIobject_name\fR | + FOREIGN DATA WRAPPER \fIobject_name\fR | + FOREIGN TABLE \fIobject_name\fR | + FUNCTION \fIfunction_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + MATERIALIZED VIEW \fIobject_name\fR | + OPERATOR \fIoperator_name\fR (\fIleft_type\fR, \fIright_type\fR) | + OPERATOR CLASS \fIobject_name\fR USING \fIindex_method\fR | + OPERATOR FAMILY \fIobject_name\fR USING \fIindex_method\fR | + [ PROCEDURAL ] LANGUAGE \fIobject_name\fR | + PROCEDURE \fIprocedure_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + ROUTINE \fIroutine_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + SCHEMA \fIobject_name\fR | + SEQUENCE \fIobject_name\fR | + SERVER \fIobject_name\fR | + TABLE \fIobject_name\fR | + TEXT SEARCH CONFIGURATION \fIobject_name\fR | + TEXT SEARCH DICTIONARY \fIobject_name\fR | + TEXT SEARCH PARSER \fIobject_name\fR | + TEXT SEARCH TEMPLATE \fIobject_name\fR | + TRANSFORM FOR \fItype_name\fR LANGUAGE \fIlang_name\fR | + TYPE \fIobject_name\fR | + VIEW \fIobject_name\fR + +and \fIaggregate_signature\fR is: + +* | +[ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] | +[ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER EXTENSION\fR +changes the definition of an installed extension\&. There are several subforms: +.PP +UPDATE +.RS 4 +This form updates the extension to a newer version\&. The extension must supply a suitable update script (or series of scripts) that can modify the currently\-installed version into the requested version\&. +.RE +.PP +SET SCHEMA +.RS 4 +This form moves the extension\*(Aqs objects into another schema\&. The extension has to be +relocatable +for this command to succeed\&. +.RE +.PP +ADD \fImember_object\fR +.RS 4 +This form adds an existing object to the extension\&. This is mainly useful in extension update scripts\&. The object will subsequently be treated as a member of the extension; notably, it can only be dropped by dropping the extension\&. +.RE +.PP +DROP \fImember_object\fR +.RS 4 +This form removes a member object from the extension\&. This is mainly useful in extension update scripts\&. The object is not dropped, only disassociated from the extension\&. +.RE +See +Section\ \&38.17 +for more information about these operations\&. +.PP +You must own the extension to use +\fBALTER EXTENSION\fR\&. The +ADD/DROP +forms require ownership of the added/dropped object as well\&. +.SH "PARAMETERS" +.PP +.PP +\fIname\fR +.RS 4 +The name of an installed extension\&. +.RE +.PP +\fInew_version\fR +.RS 4 +The desired new version of the extension\&. This can be written as either an identifier or a string literal\&. If not specified, +\fBALTER EXTENSION UPDATE\fR +attempts to update to whatever is shown as the default version in the extension\*(Aqs control file\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the extension\&. +.RE +.PP +\fIobject_name\fR +.br +\fIaggregate_name\fR +.br +\fIfunction_name\fR +.br +\fIoperator_name\fR +.br +\fIprocedure_name\fR +.br +\fIroutine_name\fR +.RS 4 +The name of an object to be added to or removed from the extension\&. Names of tables, aggregates, domains, foreign tables, functions, operators, operator classes, operator families, procedures, routines, sequences, text search objects, types, and views can be schema\-qualified\&. +.RE +.PP +\fIsource_type\fR +.RS 4 +The name of the source data type of the cast\&. +.RE +.PP +\fItarget_type\fR +.RS 4 +The name of the target data type of the cast\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of a function, procedure, or aggregate argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. Note that +\fBALTER EXTENSION\fR +does not actually pay any attention to +OUT +arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the +IN, +INOUT, and +VARIADIC +arguments\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of a function, procedure, or aggregate argument\&. Note that +\fBALTER EXTENSION\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type of a function, procedure, or aggregate argument\&. +.RE +.PP +\fIleft_type\fR +.br +\fIright_type\fR +.RS 4 +The data type(s) of the operator\*(Aqs arguments (optionally schema\-qualified)\&. Write +NONE +for the missing argument of a prefix operator\&. +.RE +.PP +PROCEDURAL +.RS 4 +This is a noise word\&. +.RE +.PP +\fItype_name\fR +.RS 4 +The name of the data type of the transform\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the language of the transform\&. +.RE +.SH "EXAMPLES" +.PP +To update the +hstore +extension to version 2\&.0: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER EXTENSION hstore UPDATE TO \*(Aq2\&.0\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To change the schema of the +hstore +extension to +utils: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER EXTENSION hstore SET SCHEMA utils; +.fi +.if n \{\ +.RE +.\} +.PP +To add an existing function to the +hstore +extension: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER EXTENSION hstore ADD FUNCTION populate_record(anyelement, hstore); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER EXTENSION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE EXTENSION (\fBCREATE_EXTENSION\fR(7)), DROP EXTENSION (\fBDROP_EXTENSION\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_FOREIGN_DATA_WRAPPER.7 b/doc/src/sgml/man7/ALTER_FOREIGN_DATA_WRAPPER.7 new file mode 100644 index 0000000..4a4728c --- /dev/null +++ b/doc/src/sgml/man7/ALTER_FOREIGN_DATA_WRAPPER.7 @@ -0,0 +1,144 @@ +'\" t +.\" Title: ALTER FOREIGN DATA WRAPPER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER FOREIGN DATA WRAPPER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_FOREIGN_DATA_WRAPPER \- change the definition of a foreign\-data wrapper +.SH "SYNOPSIS" +.sp +.nf +ALTER FOREIGN DATA WRAPPER \fIname\fR + [ HANDLER \fIhandler_function\fR | NO HANDLER ] + [ VALIDATOR \fIvalidator_function\fR | NO VALIDATOR ] + [ OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ]) ] +ALTER FOREIGN DATA WRAPPER \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER FOREIGN DATA WRAPPER \fIname\fR RENAME TO \fInew_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER FOREIGN DATA WRAPPER\fR +changes the definition of a foreign\-data wrapper\&. The first form of the command changes the support functions or the generic options of the foreign\-data wrapper (at least one clause is required)\&. The second form changes the owner of the foreign\-data wrapper\&. +.PP +Only superusers can alter foreign\-data wrappers\&. Additionally, only superusers can own foreign\-data wrappers\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing foreign\-data wrapper\&. +.RE +.PP +HANDLER \fIhandler_function\fR +.RS 4 +Specifies a new handler function for the foreign\-data wrapper\&. +.RE +.PP +NO HANDLER +.RS 4 +This is used to specify that the foreign\-data wrapper should no longer have a handler function\&. +.sp +Note that foreign tables that use a foreign\-data wrapper with no handler cannot be accessed\&. +.RE +.PP +VALIDATOR \fIvalidator_function\fR +.RS 4 +Specifies a new validator function for the foreign\-data wrapper\&. +.sp +Note that it is possible that pre\-existing options of the foreign\-data wrapper, or of dependent servers, user mappings, or foreign tables, are invalid according to the new validator\&. +PostgreSQL +does not check for this\&. It is up to the user to make sure that these options are correct before using the modified foreign\-data wrapper\&. However, any options specified in this +\fBALTER FOREIGN DATA WRAPPER\fR +command will be checked using the new validator\&. +.RE +.PP +NO VALIDATOR +.RS 4 +This is used to specify that the foreign\-data wrapper should no longer have a validator function\&. +.RE +.PP +OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] ) +.RS 4 +Change options for the foreign\-data wrapper\&. +ADD, +SET, and +DROP +specify the action to be performed\&. +ADD +is assumed if no operation is explicitly specified\&. Option names must be unique; names and values are also validated using the foreign data wrapper\*(Aqs validator function, if any\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the foreign\-data wrapper\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the foreign\-data wrapper\&. +.RE +.SH "EXAMPLES" +.PP +Change a foreign\-data wrapper +dbi, add option +foo, drop +bar: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo \*(Aq1\*(Aq, DROP \*(Aqbar\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Change the foreign\-data wrapper +dbi +validator to +bob\&.myvalidator: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob\&.myvalidator; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER FOREIGN DATA WRAPPER\fR +conforms to ISO/IEC 9075\-9 (SQL/MED), except that the +HANDLER, +VALIDATOR, +OWNER TO, and +RENAME +clauses are extensions\&. +.SH "SEE ALSO" +CREATE FOREIGN DATA WRAPPER (\fBCREATE_FOREIGN_DATA_WRAPPER\fR(7)), DROP FOREIGN DATA WRAPPER (\fBDROP_FOREIGN_DATA_WRAPPER\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_FOREIGN_TABLE.7 b/doc/src/sgml/man7/ALTER_FOREIGN_TABLE.7 new file mode 100644 index 0000000..49c2a9c --- /dev/null +++ b/doc/src/sgml/man7/ALTER_FOREIGN_TABLE.7 @@ -0,0 +1,377 @@ +'\" t +.\" Title: ALTER FOREIGN TABLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER FOREIGN TABLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_FOREIGN_TABLE \- change the definition of a foreign table +.SH "SYNOPSIS" +.sp +.nf +ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ] + \fIaction\fR [, \&.\&.\&. ] +ALTER FOREIGN TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ] + RENAME [ COLUMN ] \fIcolumn_name\fR TO \fInew_column_name\fR +ALTER FOREIGN TABLE [ IF EXISTS ] \fIname\fR + RENAME TO \fInew_name\fR +ALTER FOREIGN TABLE [ IF EXISTS ] \fIname\fR + SET SCHEMA \fInew_schema\fR + +where \fIaction\fR is one of: + + ADD [ COLUMN ] \fIcolumn_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + DROP [ COLUMN ] [ IF EXISTS ] \fIcolumn_name\fR [ RESTRICT | CASCADE ] + ALTER [ COLUMN ] \fIcolumn_name\fR [ SET DATA ] TYPE \fIdata_type\fR [ COLLATE \fIcollation\fR ] + ALTER [ COLUMN ] \fIcolumn_name\fR SET DEFAULT \fIexpression\fR + ALTER [ COLUMN ] \fIcolumn_name\fR DROP DEFAULT + ALTER [ COLUMN ] \fIcolumn_name\fR { SET | DROP } NOT NULL + ALTER [ COLUMN ] \fIcolumn_name\fR SET STATISTICS \fIinteger\fR + ALTER [ COLUMN ] \fIcolumn_name\fR SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) + ALTER [ COLUMN ] \fIcolumn_name\fR RESET ( \fIattribute_option\fR [, \&.\&.\&. ] ) + ALTER [ COLUMN ] \fIcolumn_name\fR SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } + ALTER [ COLUMN ] \fIcolumn_name\fR OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ]) + ADD \fItable_constraint\fR [ NOT VALID ] + VALIDATE CONSTRAINT \fIconstraint_name\fR + DROP CONSTRAINT [ IF EXISTS ] \fIconstraint_name\fR [ RESTRICT | CASCADE ] + DISABLE TRIGGER [ \fItrigger_name\fR | ALL | USER ] + ENABLE TRIGGER [ \fItrigger_name\fR | ALL | USER ] + ENABLE REPLICA TRIGGER \fItrigger_name\fR + ENABLE ALWAYS TRIGGER \fItrigger_name\fR + SET WITHOUT OIDS + INHERIT \fIparent_table\fR + NO INHERIT \fIparent_table\fR + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } + OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ]) +.fi +.SH "DESCRIPTION" +.PP +\fBALTER FOREIGN TABLE\fR +changes the definition of an existing foreign table\&. There are several subforms: +.PP +ADD COLUMN +.RS 4 +This form adds a new column to the foreign table, using the same syntax as +\fBCREATE FOREIGN TABLE\fR\&. Unlike the case when adding a column to a regular table, nothing happens to the underlying storage: this action simply declares that some new column is now accessible through the foreign table\&. +.RE +.PP +DROP COLUMN [ IF EXISTS ] +.RS 4 +This form drops a column from a foreign table\&. You will need to say +CASCADE +if anything outside the table depends on the column; for example, views\&. If +IF EXISTS +is specified and the column does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +SET DATA TYPE +.RS 4 +This form changes the type of a column of a foreign table\&. Again, this has no effect on any underlying storage: this action simply changes the type that +PostgreSQL +believes the column to have\&. +.RE +.PP +SET/DROP DEFAULT +.RS 4 +These forms set or remove the default value for a column\&. Default values only apply in subsequent +\fBINSERT\fR +or +\fBUPDATE\fR +commands; they do not cause rows already in the table to change\&. +.RE +.PP +SET/DROP NOT NULL +.RS 4 +Mark a column as allowing, or not allowing, null values\&. +.RE +.PP +SET STATISTICS +.RS 4 +This form sets the per\-column statistics\-gathering target for subsequent +\fBANALYZE\fR +operations\&. See the similar form of +\fBALTER TABLE\fR +for more details\&. +.RE +.PP +SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) +.br +RESET ( \fIattribute_option\fR [, \&.\&.\&. ] ) +.RS 4 +This form sets or resets per\-attribute options\&. See the similar form of +\fBALTER TABLE\fR +for more details\&. +.RE +.PP +SET STORAGE +.RS 4 +This form sets the storage mode for a column\&. See the similar form of +\fBALTER TABLE\fR +for more details\&. Note that the storage mode has no effect unless the table\*(Aqs foreign\-data wrapper chooses to pay attention to it\&. +.RE +.PP +ADD \fItable_constraint\fR [ NOT VALID ] +.RS 4 +This form adds a new constraint to a foreign table, using the same syntax as +\fBCREATE FOREIGN TABLE\fR\&. Currently only +CHECK +constraints are supported\&. +.sp +Unlike the case when adding a constraint to a regular table, nothing is done to verify the constraint is correct; rather, this action simply declares that some new condition should be assumed to hold for all rows in the foreign table\&. (See the discussion in +\fBCREATE FOREIGN TABLE\fR\&.) If the constraint is marked +NOT VALID, then it isn\*(Aqt assumed to hold, but is only recorded for possible future use\&. +.RE +.PP +VALIDATE CONSTRAINT +.RS 4 +This form marks as valid a constraint that was previously marked as +NOT VALID\&. No action is taken to verify the constraint, but future queries will assume that it holds\&. +.RE +.PP +DROP CONSTRAINT [ IF EXISTS ] +.RS 4 +This form drops the specified constraint on a foreign table\&. If +IF EXISTS +is specified and the constraint does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER +.RS 4 +These forms configure the firing of trigger(s) belonging to the foreign table\&. See the similar form of +\fBALTER TABLE\fR +for more details\&. +.RE +.PP +SET WITHOUT OIDS +.RS 4 +Backward compatibility syntax for removing the +oid +system column\&. As +oid +system columns cannot be added anymore, this never has an effect\&. +.RE +.PP +INHERIT \fIparent_table\fR +.RS 4 +This form adds the target foreign table as a new child of the specified parent table\&. See the similar form of +\fBALTER TABLE\fR +for more details\&. +.RE +.PP +NO INHERIT \fIparent_table\fR +.RS 4 +This form removes the target foreign table from the list of children of the specified parent table\&. +.RE +.PP +OWNER +.RS 4 +This form changes the owner of the foreign table to the specified user\&. +.RE +.PP +OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] ) +.RS 4 +Change options for the foreign table or one of its columns\&. +ADD, +SET, and +DROP +specify the action to be performed\&. +ADD +is assumed if no operation is explicitly specified\&. Duplicate option names are not allowed (although it\*(Aqs OK for a table option and a column option to have the same name)\&. Option names and values are also validated using the foreign data wrapper library\&. +.RE +.PP +RENAME +.RS 4 +The +RENAME +forms change the name of a foreign table or the name of an individual column in a foreign table\&. +.RE +.PP +SET SCHEMA +.RS 4 +This form moves the foreign table into another schema\&. +.RE +.PP +All the actions except +RENAME +and +SET SCHEMA +can be combined into a list of multiple alterations to apply in parallel\&. For example, it is possible to add several columns and/or alter the type of several columns in a single command\&. +.PP +If the command is written as +ALTER FOREIGN TABLE IF EXISTS \&.\&.\&. +and the foreign table does not exist, no error is thrown\&. A notice is issued in this case\&. +.PP +You must own the table to use +\fBALTER FOREIGN TABLE\fR\&. To change the schema of a foreign table, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the table\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the table\&. However, a superuser can alter ownership of any table anyway\&.) To add a column or alter a column type, you must also have +USAGE +privilege on the data type\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (possibly schema\-qualified) of an existing foreign table to alter\&. If +ONLY +is specified before the table name, only that table is altered\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are altered\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +Name of a new or existing column\&. +.RE +.PP +\fInew_column_name\fR +.RS 4 +New name for an existing column\&. +.RE +.PP +\fInew_name\fR +.RS 4 +New name for the table\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +Data type of the new column, or new data type for an existing column\&. +.RE +.PP +\fItable_constraint\fR +.RS 4 +New table constraint for the foreign table\&. +.RE +.PP +\fIconstraint_name\fR +.RS 4 +Name of an existing constraint to drop\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the dropped column or constraint (for example, views referencing the column), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the column or constraint if there are any dependent objects\&. This is the default behavior\&. +.RE +.PP +\fItrigger_name\fR +.RS 4 +Name of a single trigger to disable or enable\&. +.RE +.PP +ALL +.RS 4 +Disable or enable all triggers belonging to the foreign table\&. (This requires superuser privilege if any of the triggers are internally generated triggers\&. The core system does not add such triggers to foreign tables, but add\-on code could do so\&.) +.RE +.PP +USER +.RS 4 +Disable or enable all triggers belonging to the foreign table except for internally generated triggers\&. +.RE +.PP +\fIparent_table\fR +.RS 4 +A parent table to associate or de\-associate with this foreign table\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the table\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The name of the schema to which the table will be moved\&. +.RE +.SH "NOTES" +.PP +The key word +COLUMN +is noise and can be omitted\&. +.PP +Consistency with the foreign server is not checked when a column is added or removed with +ADD COLUMN +or +DROP COLUMN, a +NOT NULL +or +CHECK +constraint is added, or a column type is changed with +SET DATA TYPE\&. It is the user\*(Aqs responsibility to ensure that the table definition matches the remote side\&. +.PP +Refer to +\fBCREATE FOREIGN TABLE\fR +for a further description of valid parameters\&. +.SH "EXAMPLES" +.PP +To mark a column as not\-null: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL; +.fi +.if n \{\ +.RE +.\} +.PP +To change options of a foreign table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FOREIGN TABLE myschema\&.distributors OPTIONS (ADD opt1 \*(Aqvalue\*(Aq, SET opt2 \*(Aqvalue2\*(Aq, DROP opt3); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The forms +ADD, +DROP, and +SET DATA TYPE +conform with the SQL standard\&. The other forms are +PostgreSQL +extensions of the SQL standard\&. Also, the ability to specify more than one manipulation in a single +\fBALTER FOREIGN TABLE\fR +command is an extension\&. +.PP +\fBALTER FOREIGN TABLE DROP COLUMN\fR +can be used to drop the only column of a foreign table, leaving a zero\-column table\&. This is an extension of SQL, which disallows zero\-column foreign tables\&. +.SH "SEE ALSO" +CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)), DROP FOREIGN TABLE (\fBDROP_FOREIGN_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_FUNCTION.7 b/doc/src/sgml/man7/ALTER_FUNCTION.7 new file mode 100644 index 0000000..d26b1fc --- /dev/null +++ b/doc/src/sgml/man7/ALTER_FUNCTION.7 @@ -0,0 +1,348 @@ +'\" t +.\" Title: ALTER FUNCTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER FUNCTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_FUNCTION \- change the definition of a function +.SH "SYNOPSIS" +.sp +.nf +ALTER FUNCTION \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + \fIaction\fR [ \&.\&.\&. ] [ RESTRICT ] +ALTER FUNCTION \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + RENAME TO \fInew_name\fR +ALTER FUNCTION \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER FUNCTION \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + SET SCHEMA \fInew_schema\fR +ALTER FUNCTION \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR + +where \fIaction\fR is one of: + + CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT + IMMUTABLE | STABLE | VOLATILE + [ NOT ] LEAKPROOF + [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER + PARALLEL { UNSAFE | RESTRICTED | SAFE } + COST \fIexecution_cost\fR + ROWS \fIresult_rows\fR + SUPPORT \fIsupport_function\fR + SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT } + SET \fIconfiguration_parameter\fR FROM CURRENT + RESET \fIconfiguration_parameter\fR + RESET ALL +.fi +.SH "DESCRIPTION" +.PP +\fBALTER FUNCTION\fR +changes the definition of a function\&. +.PP +You must own the function to use +\fBALTER FUNCTION\fR\&. To change a function\*(Aqs schema, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the function\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the function\&. However, a superuser can alter ownership of any function anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing function\&. If no argument list is specified, the name must be unique in its schema\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. Note that +\fBALTER FUNCTION\fR +does not actually pay any attention to +OUT +arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the +IN, +INOUT, and +VARIADIC +arguments\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Note that +\fBALTER FUNCTION\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type(s) of the function\*(Aqs arguments (optionally schema\-qualified), if any\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the function\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the function\&. Note that if the function is marked +SECURITY DEFINER, it will subsequently execute as the new owner\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the function\&. +.RE +.PP +DEPENDS ON EXTENSION \fIextension_name\fR +.br +NO DEPENDS ON EXTENSION \fIextension_name\fR +.RS 4 +This form marks the function as dependent on the extension, or no longer dependent on that extension if +NO +is specified\&. A function that\*(Aqs marked as dependent on an extension is dropped when the extension is dropped, even if +CASCADE +is not specified\&. A function can depend upon multiple extensions, and will be dropped when any one of those extensions is dropped\&. +.RE +.PP +CALLED ON NULL INPUT +.br +RETURNS NULL ON NULL INPUT +.br +STRICT +.RS 4 +CALLED ON NULL INPUT +changes the function so that it will be invoked when some or all of its arguments are null\&. +RETURNS NULL ON NULL INPUT +or +STRICT +changes the function so that it is not invoked if any of its arguments are null; instead, a null result is assumed automatically\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for more information\&. +.RE +.PP +IMMUTABLE +.br +STABLE +.br +VOLATILE +.RS 4 +Change the volatility of the function to the specified setting\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for details\&. +.RE +.PP +[ EXTERNAL ] SECURITY INVOKER +.br +[ EXTERNAL ] SECURITY DEFINER +.RS 4 +Change whether the function is a security definer or not\&. The key word +EXTERNAL +is ignored for SQL conformance\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for more information about this capability\&. +.RE +.PP +PARALLEL +.RS 4 +Change whether the function is deemed safe for parallelism\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for details\&. +.RE +.PP +LEAKPROOF +.RS 4 +Change whether the function is considered leakproof or not\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for more information about this capability\&. +.RE +.PP +COST \fIexecution_cost\fR +.RS 4 +Change the estimated execution cost of the function\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for more information\&. +.RE +.PP +ROWS \fIresult_rows\fR +.RS 4 +Change the estimated number of rows returned by a set\-returning function\&. See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for more information\&. +.RE +.PP +SUPPORT \fIsupport_function\fR +.RS 4 +Set or change the planner support function to use for this function\&. See +Section\ \&38.11 +for details\&. You must be superuser to use this option\&. +.sp +This option cannot be used to remove the support function altogether, since it must name a new support function\&. Use +\fBCREATE OR REPLACE FUNCTION\fR +if you need to do that\&. +.RE +.PP +\fIconfiguration_parameter\fR +.br +\fIvalue\fR +.RS 4 +Add or change the assignment to be made to a configuration parameter when the function is called\&. If +\fIvalue\fR +is +DEFAULT +or, equivalently, +RESET +is used, the function\-local setting is removed, so that the function executes with the value present in its environment\&. Use +RESET ALL +to clear all function\-local settings\&. +SET FROM CURRENT +saves the value of the parameter that is current when +\fBALTER FUNCTION\fR +is executed as the value to be applied when the function is entered\&. +.sp +See +\fBSET\fR(7) +and +Chapter\ \&20 +for more information about allowed parameter names and values\&. +.RE +.PP +RESTRICT +.RS 4 +Ignored for conformance with the SQL standard\&. +.RE +.SH "EXAMPLES" +.PP +To rename the function +sqrt +for type +integer +to +square_root: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FUNCTION sqrt(integer) RENAME TO square_root; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the function +sqrt +for type +integer +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FUNCTION sqrt(integer) OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.PP +To change the schema of the function +sqrt +for type +integer +to +maths: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FUNCTION sqrt(integer) SET SCHEMA maths; +.fi +.if n \{\ +.RE +.\} +.PP +To mark the function +sqrt +for type +integer +as being dependent on the extension +mathlib: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FUNCTION sqrt(integer) DEPENDS ON EXTENSION mathlib; +.fi +.if n \{\ +.RE +.\} +.PP +To adjust the search path that is automatically set for a function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FUNCTION check_password(text) SET search_path = admin, pg_temp; +.fi +.if n \{\ +.RE +.\} +.PP +To disable automatic setting of +\fIsearch_path\fR +for a function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER FUNCTION check_password(text) RESET search_path; +.fi +.if n \{\ +.RE +.\} +.sp +The function will now execute with whatever search path is used by its caller\&. +.SH "COMPATIBILITY" +.PP +This statement is partially compatible with the +\fBALTER FUNCTION\fR +statement in the SQL standard\&. The standard allows more properties of a function to be modified, but does not provide the ability to rename a function, make a function a security definer, attach configuration parameter values to a function, or change the owner, schema, or volatility of a function\&. The standard also requires the +RESTRICT +key word, which is optional in +PostgreSQL\&. +.SH "SEE ALSO" +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP FUNCTION (\fBDROP_FUNCTION\fR(7)), ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)), ALTER ROUTINE (\fBALTER_ROUTINE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_GROUP.7 b/doc/src/sgml/man7/ALTER_GROUP.7 new file mode 100644 index 0000000..6ec91e5 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_GROUP.7 @@ -0,0 +1,113 @@ +'\" t +.\" Title: ALTER GROUP +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER GROUP" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_GROUP \- change role name or membership +.SH "SYNOPSIS" +.sp +.nf +ALTER GROUP \fIrole_specification\fR ADD USER \fIuser_name\fR [, \&.\&.\&. ] +ALTER GROUP \fIrole_specification\fR DROP USER \fIuser_name\fR [, \&.\&.\&. ] + +where \fIrole_specification\fR can be: + + \fIrole_name\fR + | CURRENT_ROLE + | CURRENT_USER + | SESSION_USER + +ALTER GROUP \fIgroup_name\fR RENAME TO \fInew_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER GROUP\fR +changes the attributes of a user group\&. This is an obsolete command, though still accepted for backwards compatibility, because groups (and users too) have been superseded by the more general concept of roles\&. +.PP +The first two variants add users to a group or remove them from a group\&. (Any role can play the part of either a +\(lquser\(rq +or a +\(lqgroup\(rq +for this purpose\&.) These variants are effectively equivalent to granting or revoking membership in the role named as the +\(lqgroup\(rq; so the preferred way to do this is to use +\fBGRANT\fR +or +\fBREVOKE\fR\&. +.PP +The third variant changes the name of the group\&. This is exactly equivalent to renaming the role with +\fBALTER ROLE\fR\&. +.SH "PARAMETERS" +.PP +\fIgroup_name\fR +.RS 4 +The name of the group (role) to modify\&. +.RE +.PP +\fIuser_name\fR +.RS 4 +Users (roles) that are to be added to or removed from the group\&. The users must already exist; +\fBALTER GROUP\fR +does not create or drop users\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the group\&. +.RE +.SH "EXAMPLES" +.PP +Add users to a group: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER GROUP staff ADD USER karl, john; +.fi +.if n \{\ +.RE +.\} +.sp +Remove a user from a group: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER GROUP workers DROP USER beth; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER GROUP\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBGRANT\fR(7), \fBREVOKE\fR(7), ALTER ROLE (\fBALTER_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_INDEX.7 b/doc/src/sgml/man7/ALTER_INDEX.7 new file mode 100644 index 0000000..79b3923 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_INDEX.7 @@ -0,0 +1,237 @@ +'\" t +.\" Title: ALTER INDEX +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER INDEX" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_INDEX \- change the definition of an index +.SH "SYNOPSIS" +.sp +.nf +ALTER INDEX [ IF EXISTS ] \fIname\fR RENAME TO \fInew_name\fR +ALTER INDEX [ IF EXISTS ] \fIname\fR SET TABLESPACE \fItablespace_name\fR +ALTER INDEX \fIname\fR ATTACH PARTITION \fIindex_name\fR +ALTER INDEX \fIname\fR [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR +ALTER INDEX [ IF EXISTS ] \fIname\fR SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +ALTER INDEX [ IF EXISTS ] \fIname\fR RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] ) +ALTER INDEX [ IF EXISTS ] \fIname\fR ALTER [ COLUMN ] \fIcolumn_number\fR + SET STATISTICS \fIinteger\fR +ALTER INDEX ALL IN TABLESPACE \fIname\fR [ OWNED BY \fIrole_name\fR [, \&.\&.\&. ] ] + SET TABLESPACE \fInew_tablespace\fR [ NOWAIT ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER INDEX\fR +changes the definition of an existing index\&. There are several subforms described below\&. Note that the lock level required may differ for each subform\&. An +ACCESS EXCLUSIVE +lock is held unless explicitly noted\&. When multiple subcommands are listed, the lock held will be the strictest one required from any subcommand\&. +.PP +RENAME +.RS 4 +The +RENAME +form changes the name of the index\&. If the index is associated with a table constraint (either +UNIQUE, +PRIMARY KEY, or +EXCLUDE), the constraint is renamed as well\&. There is no effect on the stored data\&. +.sp +Renaming an index acquires a +SHARE UPDATE EXCLUSIVE +lock\&. +.RE +.PP +SET TABLESPACE +.RS 4 +This form changes the index\*(Aqs tablespace to the specified tablespace and moves the data file(s) associated with the index to the new tablespace\&. To change the tablespace of an index, you must own the index and have +CREATE +privilege on the new tablespace\&. All indexes in the current database in a tablespace can be moved by using the +ALL IN TABLESPACE +form, which will lock all indexes to be moved and then move each one\&. This form also supports +OWNED BY, which will only move indexes owned by the roles specified\&. If the +NOWAIT +option is specified then the command will fail if it is unable to acquire all of the locks required immediately\&. Note that system catalogs will not be moved by this command, use +\fBALTER DATABASE\fR +or explicit +\fBALTER INDEX\fR +invocations instead if desired\&. See also +\fBCREATE TABLESPACE\fR\&. +.RE +.PP +ATTACH PARTITION +.RS 4 +Causes the named index to become attached to the altered index\&. The named index must be on a partition of the table containing the index being altered, and have an equivalent definition\&. An attached index cannot be dropped by itself, and will automatically be dropped if its parent index is dropped\&. +.RE +.PP +DEPENDS ON EXTENSION \fIextension_name\fR +.br +NO DEPENDS ON EXTENSION \fIextension_name\fR +.RS 4 +This form marks the index as dependent on the extension, or no longer dependent on that extension if +NO +is specified\&. An index that\*(Aqs marked as dependent on an extension is automatically dropped when the extension is dropped\&. +.RE +.PP +SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This form changes one or more index\-method\-specific storage parameters for the index\&. See +\fBCREATE INDEX\fR +for details on the available parameters\&. Note that the index contents will not be modified immediately by this command; depending on the parameter you might need to rebuild the index with +\fBREINDEX\fR +to get the desired effects\&. +.RE +.PP +RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] ) +.RS 4 +This form resets one or more index\-method\-specific storage parameters to their defaults\&. As with +SET, a +REINDEX +might be needed to update the index entirely\&. +.RE +.PP +ALTER [ COLUMN ] \fIcolumn_number\fR SET STATISTICS \fIinteger\fR +.RS 4 +This form sets the per\-column statistics\-gathering target for subsequent +\fBANALYZE\fR +operations, though can be used only on index columns that are defined as an expression\&. Since expressions lack a unique name, we refer to them using the ordinal number of the index column\&. The target can be set in the range 0 to 10000; alternatively, set it to \-1 to revert to using the system default statistics target (default_statistics_target)\&. For more information on the use of statistics by the +PostgreSQL +query planner, refer to +Section\ \&14.2\&. +.RE +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the index does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIcolumn_number\fR +.RS 4 +The ordinal number refers to the ordinal (left\-to\-right) position of the index column\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (possibly schema\-qualified) of an existing index to alter\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the index\&. +.RE +.PP +\fItablespace_name\fR +.RS 4 +The tablespace to which the index will be moved\&. +.RE +.PP +\fIextension_name\fR +.RS 4 +The name of the extension that the index is to depend on\&. +.RE +.PP +\fIstorage_parameter\fR +.RS 4 +The name of an index\-method\-specific storage parameter\&. +.RE +.PP +\fIvalue\fR +.RS 4 +The new value for an index\-method\-specific storage parameter\&. This might be a number or a word depending on the parameter\&. +.RE +.SH "NOTES" +.PP +These operations are also possible using +\fBALTER TABLE\fR\&. +\fBALTER INDEX\fR +is in fact just an alias for the forms of +\fBALTER TABLE\fR +that apply to indexes\&. +.PP +There was formerly an +\fBALTER INDEX OWNER\fR +variant, but this is now ignored (with a warning)\&. An index cannot have an owner different from its table\*(Aqs owner\&. Changing the table\*(Aqs owner automatically changes the index as well\&. +.PP +Changing any part of a system catalog index is not permitted\&. +.SH "EXAMPLES" +.PP +To rename an existing index: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER INDEX distributors RENAME TO suppliers; +.fi +.if n \{\ +.RE +.\} +.PP +To move an index to a different tablespace: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER INDEX distributors SET TABLESPACE fasttablespace; +.fi +.if n \{\ +.RE +.\} +.PP +To change an index\*(Aqs fill factor (assuming that the index method supports it): +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER INDEX distributors SET (fillfactor = 75); +REINDEX INDEX distributors; +.fi +.if n \{\ +.RE +.\} +.PP +Set the statistics\-gathering target for an expression index: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX coord_idx ON measured (x, y, (z + t)); +ALTER INDEX coord_idx ALTER COLUMN 3 SET STATISTICS 1000; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER INDEX\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE INDEX (\fBCREATE_INDEX\fR(7)), \fBREINDEX\fR(7) diff --git a/doc/src/sgml/man7/ALTER_LANGUAGE.7 b/doc/src/sgml/man7/ALTER_LANGUAGE.7 new file mode 100644 index 0000000..92d7254 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_LANGUAGE.7 @@ -0,0 +1,65 @@ +'\" t +.\" Title: ALTER LANGUAGE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER LANGUAGE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_LANGUAGE \- change the definition of a procedural language +.SH "SYNOPSIS" +.sp +.nf +ALTER [ PROCEDURAL ] LANGUAGE \fIname\fR RENAME TO \fInew_name\fR +ALTER [ PROCEDURAL ] LANGUAGE \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +.fi +.SH "DESCRIPTION" +.PP +\fBALTER LANGUAGE\fR +changes the definition of a procedural language\&. The only functionality is to rename the language or assign a new owner\&. You must be superuser or owner of the language to use +\fBALTER LANGUAGE\fR\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +Name of a language +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the language +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the language +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER LANGUAGE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE LANGUAGE (\fBCREATE_LANGUAGE\fR(7)), DROP LANGUAGE (\fBDROP_LANGUAGE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_LARGE_OBJECT.7 b/doc/src/sgml/man7/ALTER_LARGE_OBJECT.7 new file mode 100644 index 0000000..9b8895f --- /dev/null +++ b/doc/src/sgml/man7/ALTER_LARGE_OBJECT.7 @@ -0,0 +1,61 @@ +'\" t +.\" Title: ALTER LARGE OBJECT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER LARGE OBJECT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_LARGE_OBJECT \- change the definition of a large object +.SH "SYNOPSIS" +.sp +.nf +ALTER LARGE OBJECT \fIlarge_object_oid\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +.fi +.SH "DESCRIPTION" +.PP +\fBALTER LARGE OBJECT\fR +changes the definition of a large object\&. +.PP +You must own the large object to use +\fBALTER LARGE OBJECT\fR\&. To alter the owner, you must also be a direct or indirect member of the new owning role\&. (However, a superuser can alter any large object anyway\&.) Currently, the only functionality is to assign a new owner, so both restrictions always apply\&. +.SH "PARAMETERS" +.PP +\fIlarge_object_oid\fR +.RS 4 +OID of the large object to be altered +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the large object +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER LARGE OBJECT\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +Chapter\ \&35 diff --git a/doc/src/sgml/man7/ALTER_MATERIALIZED_VIEW.7 b/doc/src/sgml/man7/ALTER_MATERIALIZED_VIEW.7 new file mode 100644 index 0000000..7ed5e03 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_MATERIALIZED_VIEW.7 @@ -0,0 +1,142 @@ +'\" t +.\" Title: ALTER MATERIALIZED VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER MATERIALIZED VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_MATERIALIZED_VIEW \- change the definition of a materialized view +.SH "SYNOPSIS" +.sp +.nf +ALTER MATERIALIZED VIEW [ IF EXISTS ] \fIname\fR + \fIaction\fR [, \&.\&.\&. ] +ALTER MATERIALIZED VIEW \fIname\fR + [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR +ALTER MATERIALIZED VIEW [ IF EXISTS ] \fIname\fR + RENAME [ COLUMN ] \fIcolumn_name\fR TO \fInew_column_name\fR +ALTER MATERIALIZED VIEW [ IF EXISTS ] \fIname\fR + RENAME TO \fInew_name\fR +ALTER MATERIALIZED VIEW [ IF EXISTS ] \fIname\fR + SET SCHEMA \fInew_schema\fR +ALTER MATERIALIZED VIEW ALL IN TABLESPACE \fIname\fR [ OWNED BY \fIrole_name\fR [, \&.\&.\&. ] ] + SET TABLESPACE \fInew_tablespace\fR [ NOWAIT ] + +where \fIaction\fR is one of: + + ALTER [ COLUMN ] \fIcolumn_name\fR SET STATISTICS \fIinteger\fR + ALTER [ COLUMN ] \fIcolumn_name\fR SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) + ALTER [ COLUMN ] \fIcolumn_name\fR RESET ( \fIattribute_option\fR [, \&.\&.\&. ] ) + ALTER [ COLUMN ] \fIcolumn_name\fR SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } + ALTER [ COLUMN ] \fIcolumn_name\fR SET COMPRESSION \fIcompression_method\fR + CLUSTER ON \fIindex_name\fR + SET WITHOUT CLUSTER + SET ACCESS METHOD \fInew_access_method\fR + SET TABLESPACE \fInew_tablespace\fR + SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) + RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] ) + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +.fi +.SH "DESCRIPTION" +.PP +\fBALTER MATERIALIZED VIEW\fR +changes various auxiliary properties of an existing materialized view\&. +.PP +You must own the materialized view to use +\fBALTER MATERIALIZED VIEW\fR\&. To change a materialized view\*(Aqs schema, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the materialized view\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the materialized view\&. However, a superuser can alter ownership of any view anyway\&.) +.PP +The statement subforms and actions available for +\fBALTER MATERIALIZED VIEW\fR +are a subset of those available for +\fBALTER TABLE\fR, and have the same meaning when used for materialized views\&. See the descriptions for +\fBALTER TABLE\fR +for details\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing materialized view\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +Name of a new or existing column\&. +.RE +.PP +\fIextension_name\fR +.RS 4 +The name of the extension that the materialized view is to depend on (or no longer dependent on, if +NO +is specified)\&. A materialized view that\*(Aqs marked as dependent on an extension is automatically dropped when the extension is dropped\&. +.RE +.PP +\fInew_column_name\fR +.RS 4 +New name for an existing column\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the materialized view\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the materialized view\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the materialized view\&. +.RE +.SH "EXAMPLES" +.PP +To rename the materialized view +foo +to +bar: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER MATERIALIZED VIEW foo RENAME TO bar; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER MATERIALIZED VIEW\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE MATERIALIZED VIEW (\fBCREATE_MATERIALIZED_VIEW\fR(7)), DROP MATERIALIZED VIEW (\fBDROP_MATERIALIZED_VIEW\fR(7)), REFRESH MATERIALIZED VIEW (\fBREFRESH_MATERIALIZED_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_OPERATOR.7 b/doc/src/sgml/man7/ALTER_OPERATOR.7 new file mode 100644 index 0000000..dc80e14 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_OPERATOR.7 @@ -0,0 +1,130 @@ +'\" t +.\" Title: ALTER OPERATOR +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER OPERATOR" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_OPERATOR \- change the definition of an operator +.SH "SYNOPSIS" +.sp +.nf +ALTER OPERATOR \fIname\fR ( { \fIleft_type\fR | NONE } , \fIright_type\fR ) + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } + +ALTER OPERATOR \fIname\fR ( { \fIleft_type\fR | NONE } , \fIright_type\fR ) + SET SCHEMA \fInew_schema\fR + +ALTER OPERATOR \fIname\fR ( { \fIleft_type\fR | NONE } , \fIright_type\fR ) + SET ( { RESTRICT = { \fIres_proc\fR | NONE } + | JOIN = { \fIjoin_proc\fR | NONE } + } [, \&.\&.\&. ] ) +.fi +.SH "DESCRIPTION" +.PP +\fBALTER OPERATOR\fR +changes the definition of an operator\&. +.PP +You must own the operator to use +\fBALTER OPERATOR\fR\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the operator\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the operator\&. However, a superuser can alter ownership of any operator anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing operator\&. +.RE +.PP +\fIleft_type\fR +.RS 4 +The data type of the operator\*(Aqs left operand; write +NONE +if the operator has no left operand\&. +.RE +.PP +\fIright_type\fR +.RS 4 +The data type of the operator\*(Aqs right operand\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the operator\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the operator\&. +.RE +.PP +\fIres_proc\fR +.RS 4 +The restriction selectivity estimator function for this operator; write NONE to remove existing selectivity estimator\&. +.RE +.PP +\fIjoin_proc\fR +.RS 4 +The join selectivity estimator function for this operator; write NONE to remove existing selectivity estimator\&. +.RE +.SH "EXAMPLES" +.PP +Change the owner of a custom operator +a @@ b +for type +text: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER OPERATOR @@ (text, text) OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.PP +Change the restriction and join selectivity estimator functions of a custom operator +a && b +for type +int[]: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER OPERATOR && (_int4, _int4) SET (RESTRICT = _int_contsel, JOIN = _int_contjoinsel); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER OPERATOR\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE OPERATOR (\fBCREATE_OPERATOR\fR(7)), DROP OPERATOR (\fBDROP_OPERATOR\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_OPERATOR_CLASS.7 b/doc/src/sgml/man7/ALTER_OPERATOR_CLASS.7 new file mode 100644 index 0000000..b445edf --- /dev/null +++ b/doc/src/sgml/man7/ALTER_OPERATOR_CLASS.7 @@ -0,0 +1,85 @@ +'\" t +.\" Title: ALTER OPERATOR CLASS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER OPERATOR CLASS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_OPERATOR_CLASS \- change the definition of an operator class +.SH "SYNOPSIS" +.sp +.nf +ALTER OPERATOR CLASS \fIname\fR USING \fIindex_method\fR + RENAME TO \fInew_name\fR + +ALTER OPERATOR CLASS \fIname\fR USING \fIindex_method\fR + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } + +ALTER OPERATOR CLASS \fIname\fR USING \fIindex_method\fR + SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER OPERATOR CLASS\fR +changes the definition of an operator class\&. +.PP +You must own the operator class to use +\fBALTER OPERATOR CLASS\fR\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the operator class\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the operator class\&. However, a superuser can alter ownership of any operator class anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing operator class\&. +.RE +.PP +\fIindex_method\fR +.RS 4 +The name of the index method this operator class is for\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the operator class\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the operator class\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the operator class\&. +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER OPERATOR CLASS\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), DROP OPERATOR CLASS (\fBDROP_OPERATOR_CLASS\fR(7)), ALTER OPERATOR FAMILY (\fBALTER_OPERATOR_FAMILY\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_OPERATOR_FAMILY.7 b/doc/src/sgml/man7/ALTER_OPERATOR_FAMILY.7 new file mode 100644 index 0000000..20713dc --- /dev/null +++ b/doc/src/sgml/man7/ALTER_OPERATOR_FAMILY.7 @@ -0,0 +1,259 @@ +'\" t +.\" Title: ALTER OPERATOR FAMILY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER OPERATOR FAMILY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_OPERATOR_FAMILY \- change the definition of an operator family +.SH "SYNOPSIS" +.sp +.nf +ALTER OPERATOR FAMILY \fIname\fR USING \fIindex_method\fR ADD + { OPERATOR \fIstrategy_number\fR \fIoperator_name\fR ( \fIop_type\fR, \fIop_type\fR ) + [ FOR SEARCH | FOR ORDER BY \fIsort_family_name\fR ] + | FUNCTION \fIsupport_number\fR [ ( \fIop_type\fR [ , \fIop_type\fR ] ) ] + \fIfunction_name\fR [ ( \fIargument_type\fR [, \&.\&.\&.] ) ] + } [, \&.\&.\&. ] + +ALTER OPERATOR FAMILY \fIname\fR USING \fIindex_method\fR DROP + { OPERATOR \fIstrategy_number\fR ( \fIop_type\fR [ , \fIop_type\fR ] ) + | FUNCTION \fIsupport_number\fR ( \fIop_type\fR [ , \fIop_type\fR ] ) + } [, \&.\&.\&. ] + +ALTER OPERATOR FAMILY \fIname\fR USING \fIindex_method\fR + RENAME TO \fInew_name\fR + +ALTER OPERATOR FAMILY \fIname\fR USING \fIindex_method\fR + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } + +ALTER OPERATOR FAMILY \fIname\fR USING \fIindex_method\fR + SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER OPERATOR FAMILY\fR +changes the definition of an operator family\&. You can add operators and support functions to the family, remove them from the family, or change the family\*(Aqs name or owner\&. +.PP +When operators and support functions are added to a family with +\fBALTER OPERATOR FAMILY\fR, they are not part of any specific operator class within the family, but are just +\(lqloose\(rq +within the family\&. This indicates that these operators and functions are compatible with the family\*(Aqs semantics, but are not required for correct functioning of any specific index\&. (Operators and functions that are so required should be declared as part of an operator class, instead; see +CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7))\&.) +PostgreSQL +will allow loose members of a family to be dropped from the family at any time, but members of an operator class cannot be dropped without dropping the whole class and any indexes that depend on it\&. Typically, single\-data\-type operators and functions are part of operator classes because they are needed to support an index on that specific data type, while cross\-data\-type operators and functions are made loose members of the family\&. +.PP +You must be a superuser to use +\fBALTER OPERATOR FAMILY\fR\&. (This restriction is made because an erroneous operator family definition could confuse or even crash the server\&.) +.PP +\fBALTER OPERATOR FAMILY\fR +does not presently check whether the operator family definition includes all the operators and functions required by the index method, nor whether the operators and functions form a self\-consistent set\&. It is the user\*(Aqs responsibility to define a valid operator family\&. +.PP +Refer to +Section\ \&38.16 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing operator family\&. +.RE +.PP +\fIindex_method\fR +.RS 4 +The name of the index method this operator family is for\&. +.RE +.PP +\fIstrategy_number\fR +.RS 4 +The index method\*(Aqs strategy number for an operator associated with the operator family\&. +.RE +.PP +\fIoperator_name\fR +.RS 4 +The name (optionally schema\-qualified) of an operator associated with the operator family\&. +.RE +.PP +\fIop_type\fR +.RS 4 +In an +OPERATOR +clause, the operand data type(s) of the operator, or +NONE +to signify a prefix operator\&. Unlike the comparable syntax in +\fBCREATE OPERATOR CLASS\fR, the operand data types must always be specified\&. +.sp +In an +ADD FUNCTION +clause, the operand data type(s) the function is intended to support, if different from the input data type(s) of the function\&. For B\-tree comparison functions and hash functions it is not necessary to specify +\fIop_type\fR +since the function\*(Aqs input data type(s) are always the correct ones to use\&. For B\-tree sort support functions, B\-Tree equal image functions, and all functions in GiST, SP\-GiST and GIN operator classes, it is necessary to specify the operand data type(s) the function is to be used with\&. +.sp +In a +DROP FUNCTION +clause, the operand data type(s) the function is intended to support must be specified\&. +.RE +.PP +\fIsort_family_name\fR +.RS 4 +The name (optionally schema\-qualified) of an existing +btree +operator family that describes the sort ordering associated with an ordering operator\&. +.sp +If neither +FOR SEARCH +nor +FOR ORDER BY +is specified, +FOR SEARCH +is the default\&. +.RE +.PP +\fIsupport_number\fR +.RS 4 +The index method\*(Aqs support function number for a function associated with the operator family\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +The name (optionally schema\-qualified) of a function that is an index method support function for the operator family\&. If no argument list is specified, the name must be unique in its schema\&. +.RE +.PP +\fIargument_type\fR +.RS 4 +The parameter data type(s) of the function\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the operator family\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the operator family\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the operator family\&. +.RE +.PP +The +OPERATOR +and +FUNCTION +clauses can appear in any order\&. +.SH "NOTES" +.PP +Notice that the +DROP +syntax only specifies the +\(lqslot\(rq +in the operator family, by strategy or support number and input data type(s)\&. The name of the operator or function occupying the slot is not mentioned\&. Also, for +DROP FUNCTION +the type(s) to specify are the input data type(s) the function is intended to support; for GiST, SP\-GiST and GIN indexes this might have nothing to do with the actual input argument types of the function\&. +.PP +Because the index machinery does not check access permissions on functions before using them, including a function or operator in an operator family is tantamount to granting public execute permission on it\&. This is usually not an issue for the sorts of functions that are useful in an operator family\&. +.PP +The operators should not be defined by SQL functions\&. An SQL function is likely to be inlined into the calling query, which will prevent the optimizer from recognizing that the query matches an index\&. +.PP +Before +PostgreSQL +8\&.4, the +OPERATOR +clause could include a +RECHECK +option\&. This is no longer supported because whether an index operator is +\(lqlossy\(rq +is now determined on\-the\-fly at run time\&. This allows efficient handling of cases where an operator might or might not be lossy\&. +.SH "EXAMPLES" +.PP +The following example command adds cross\-data\-type operators and support functions to an operator family that already contains B\-tree operator classes for data types +int4 +and +int2\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER OPERATOR FAMILY integer_ops USING btree ADD + + \-\- int4 vs int2 + OPERATOR 1 < (int4, int2) , + OPERATOR 2 <= (int4, int2) , + OPERATOR 3 = (int4, int2) , + OPERATOR 4 >= (int4, int2) , + OPERATOR 5 > (int4, int2) , + FUNCTION 1 btint42cmp(int4, int2) , + + \-\- int2 vs int4 + OPERATOR 1 < (int2, int4) , + OPERATOR 2 <= (int2, int4) , + OPERATOR 3 = (int2, int4) , + OPERATOR 4 >= (int2, int4) , + OPERATOR 5 > (int2, int4) , + FUNCTION 1 btint24cmp(int2, int4) ; +.fi +.if n \{\ +.RE +.\} +.PP +To remove these entries again: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER OPERATOR FAMILY integer_ops USING btree DROP + + \-\- int4 vs int2 + OPERATOR 1 (int4, int2) , + OPERATOR 2 (int4, int2) , + OPERATOR 3 (int4, int2) , + OPERATOR 4 (int4, int2) , + OPERATOR 5 (int4, int2) , + FUNCTION 1 (int4, int2) , + + \-\- int2 vs int4 + OPERATOR 1 (int2, int4) , + OPERATOR 2 (int2, int4) , + OPERATOR 3 (int2, int4) , + OPERATOR 4 (int2, int4) , + OPERATOR 5 (int2, int4) , + FUNCTION 1 (int2, int4) ; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER OPERATOR FAMILY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE OPERATOR FAMILY (\fBCREATE_OPERATOR_FAMILY\fR(7)), DROP OPERATOR FAMILY (\fBDROP_OPERATOR_FAMILY\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), ALTER OPERATOR CLASS (\fBALTER_OPERATOR_CLASS\fR(7)), DROP OPERATOR CLASS (\fBDROP_OPERATOR_CLASS\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_POLICY.7 b/doc/src/sgml/man7/ALTER_POLICY.7 new file mode 100644 index 0000000..4c18353 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_POLICY.7 @@ -0,0 +1,108 @@ +'\" t +.\" Title: ALTER POLICY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER POLICY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_POLICY \- change the definition of a row\-level security policy +.SH "SYNOPSIS" +.sp +.nf +ALTER POLICY \fIname\fR ON \fItable_name\fR RENAME TO \fInew_name\fR + +ALTER POLICY \fIname\fR ON \fItable_name\fR + [ TO { \fIrole_name\fR | PUBLIC | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, \&.\&.\&.] ] + [ USING ( \fIusing_expression\fR ) ] + [ WITH CHECK ( \fIcheck_expression\fR ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER POLICY\fR +changes the definition of an existing row\-level security policy\&. Note that +\fBALTER POLICY\fR +only allows the set of roles to which the policy applies and the +USING +and +WITH CHECK +expressions to be modified\&. To change other properties of a policy, such as the command to which it applies or whether it is permissive or restrictive, the policy must be dropped and recreated\&. +.PP +To use +\fBALTER POLICY\fR, you must own the table that the policy applies to\&. +.PP +In the second form of +\fBALTER POLICY\fR, the role list, +\fIusing_expression\fR, and +\fIcheck_expression\fR +are replaced independently if specified\&. When one of those clauses is omitted, the corresponding part of the policy is unchanged\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing policy to alter\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table that the policy is on\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the policy\&. +.RE +.PP +\fIrole_name\fR +.RS 4 +The role(s) to which the policy applies\&. Multiple roles can be specified at one time\&. To apply the policy to all roles, use +PUBLIC\&. +.RE +.PP +\fIusing_expression\fR +.RS 4 +The +USING +expression for the policy\&. See +CREATE POLICY (\fBCREATE_POLICY\fR(7)) +for details\&. +.RE +.PP +\fIcheck_expression\fR +.RS 4 +The +WITH CHECK +expression for the policy\&. See +CREATE POLICY (\fBCREATE_POLICY\fR(7)) +for details\&. +.RE +.SH "COMPATIBILITY" +.PP +\fBALTER POLICY\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE POLICY (\fBCREATE_POLICY\fR(7)), DROP POLICY (\fBDROP_POLICY\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_PROCEDURE.7 b/doc/src/sgml/man7/ALTER_PROCEDURE.7 new file mode 100644 index 0000000..a78dde7 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_PROCEDURE.7 @@ -0,0 +1,263 @@ +'\" t +.\" Title: ALTER PROCEDURE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER PROCEDURE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_PROCEDURE \- change the definition of a procedure +.SH "SYNOPSIS" +.sp +.nf +ALTER PROCEDURE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + \fIaction\fR [ \&.\&.\&. ] [ RESTRICT ] +ALTER PROCEDURE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + RENAME TO \fInew_name\fR +ALTER PROCEDURE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER PROCEDURE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + SET SCHEMA \fInew_schema\fR +ALTER PROCEDURE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR + +where \fIaction\fR is one of: + + [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER + SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT } + SET \fIconfiguration_parameter\fR FROM CURRENT + RESET \fIconfiguration_parameter\fR + RESET ALL +.fi +.SH "DESCRIPTION" +.PP +\fBALTER PROCEDURE\fR +changes the definition of a procedure\&. +.PP +You must own the procedure to use +\fBALTER PROCEDURE\fR\&. To change a procedure\*(Aqs schema, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the procedure\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the procedure\&. However, a superuser can alter ownership of any procedure anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing procedure\&. If no argument list is specified, the name must be unique in its schema\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Note that +\fBALTER PROCEDURE\fR +does not actually pay any attention to argument names, since only the argument data types are used to determine the procedure\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type(s) of the procedure\*(Aqs arguments (optionally schema\-qualified), if any\&. See +DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)) +for the details of how the procedure is looked up using the argument data type(s)\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the procedure\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the procedure\&. Note that if the procedure is marked +SECURITY DEFINER, it will subsequently execute as the new owner\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the procedure\&. +.RE +.PP +\fIextension_name\fR +.RS 4 +This form marks the procedure as dependent on the extension, or no longer dependent on the extension if +NO +is specified\&. A procedure that\*(Aqs marked as dependent on an extension is dropped when the extension is dropped, even if cascade is not specified\&. A procedure can depend upon multiple extensions, and will be dropped when any one of those extensions is dropped\&. +.RE +.PP +[ EXTERNAL ] SECURITY INVOKER +.br +[ EXTERNAL ] SECURITY DEFINER +.RS 4 +Change whether the procedure is a security definer or not\&. The key word +EXTERNAL +is ignored for SQL conformance\&. See +CREATE PROCEDURE (\fBCREATE_PROCEDURE\fR(7)) +for more information about this capability\&. +.RE +.PP +\fIconfiguration_parameter\fR +.br +\fIvalue\fR +.RS 4 +Add or change the assignment to be made to a configuration parameter when the procedure is called\&. If +\fIvalue\fR +is +DEFAULT +or, equivalently, +RESET +is used, the procedure\-local setting is removed, so that the procedure executes with the value present in its environment\&. Use +RESET ALL +to clear all procedure\-local settings\&. +SET FROM CURRENT +saves the value of the parameter that is current when +\fBALTER PROCEDURE\fR +is executed as the value to be applied when the procedure is entered\&. +.sp +See +\fBSET\fR(7) +and +Chapter\ \&20 +for more information about allowed parameter names and values\&. +.RE +.PP +RESTRICT +.RS 4 +Ignored for conformance with the SQL standard\&. +.RE +.SH "EXAMPLES" +.PP +To rename the procedure +insert_data +with two arguments of type +integer +to +insert_record: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PROCEDURE insert_data(integer, integer) RENAME TO insert_record; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the procedure +insert_data +with two arguments of type +integer +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PROCEDURE insert_data(integer, integer) OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.PP +To change the schema of the procedure +insert_data +with two arguments of type +integer +to +accounting: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PROCEDURE insert_data(integer, integer) SET SCHEMA accounting; +.fi +.if n \{\ +.RE +.\} +.PP +To mark the procedure +insert_data(integer, integer) +as being dependent on the extension +myext: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PROCEDURE insert_data(integer, integer) DEPENDS ON EXTENSION myext; +.fi +.if n \{\ +.RE +.\} +.PP +To adjust the search path that is automatically set for a procedure: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PROCEDURE check_password(text) SET search_path = admin, pg_temp; +.fi +.if n \{\ +.RE +.\} +.PP +To disable automatic setting of +\fIsearch_path\fR +for a procedure: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PROCEDURE check_password(text) RESET search_path; +.fi +.if n \{\ +.RE +.\} +.sp +The procedure will now execute with whatever search path is used by its caller\&. +.SH "COMPATIBILITY" +.PP +This statement is partially compatible with the +\fBALTER PROCEDURE\fR +statement in the SQL standard\&. The standard allows more properties of a procedure to be modified, but does not provide the ability to rename a procedure, make a procedure a security definer, attach configuration parameter values to a procedure, or change the owner, schema, or volatility of a procedure\&. The standard also requires the +RESTRICT +key word, which is optional in +PostgreSQL\&. +.SH "SEE ALSO" +CREATE PROCEDURE (\fBCREATE_PROCEDURE\fR(7)), DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)), ALTER FUNCTION (\fBALTER_FUNCTION\fR(7)), ALTER ROUTINE (\fBALTER_ROUTINE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_PUBLICATION.7 b/doc/src/sgml/man7/ALTER_PUBLICATION.7 new file mode 100644 index 0000000..30f6ff8 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_PUBLICATION.7 @@ -0,0 +1,221 @@ +'\" t +.\" Title: ALTER PUBLICATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER PUBLICATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_PUBLICATION \- change the definition of a publication +.SH "SYNOPSIS" +.sp +.nf +ALTER PUBLICATION \fIname\fR ADD \fIpublication_object\fR [, \&.\&.\&.] +ALTER PUBLICATION \fIname\fR SET \fIpublication_object\fR [, \&.\&.\&.] +ALTER PUBLICATION \fIname\fR DROP \fIpublication_object\fR [, \&.\&.\&.] +ALTER PUBLICATION \fIname\fR SET ( \fIpublication_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +ALTER PUBLICATION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER PUBLICATION \fIname\fR RENAME TO \fInew_name\fR + +where \fIpublication_object\fR is one of: + + TABLE [ ONLY ] \fItable_name\fR [ * ] [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] [ WHERE ( \fIexpression\fR ) ] [, \&.\&.\&. ] + TABLES IN SCHEMA { \fIschema_name\fR | CURRENT_SCHEMA } [, \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +The command +\fBALTER PUBLICATION\fR +can change the attributes of a publication\&. +.PP +The first three variants change which tables/schemas are part of the publication\&. The +SET +clause will replace the list of tables/schemas in the publication with the specified list; the existing tables/schemas that were present in the publication will be removed\&. The +ADD +and +DROP +clauses will add and remove one or more tables/schemas from the publication\&. Note that adding tables/schemas to a publication that is already subscribed to will require an +ALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION +action on the subscribing side in order to become effective\&. Note also that +DROP TABLES IN SCHEMA +will not drop any schema tables that were specified using +FOR TABLE/ +ADD TABLE, and the combination of +DROP +with a +WHERE +clause is not allowed\&. +.PP +The fourth variant of this command listed in the synopsis can change all of the publication properties specified in +CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7))\&. Properties not mentioned in the command retain their previous settings\&. +.PP +The remaining variants change the owner and the name of the publication\&. +.PP +You must own the publication to use +\fBALTER PUBLICATION\fR\&. Adding a table to a publication additionally requires owning that table\&. The +ADD TABLES IN SCHEMA +and +SET TABLES IN SCHEMA +to a publication requires the invoking user to be a superuser\&. To alter the owner, you must also be a direct or indirect member of the new owning role\&. The new owner must have +CREATE +privilege on the database\&. Also, the new owner of a +FOR ALL TABLES +or +FOR TABLES IN SCHEMA +publication must be a superuser\&. However, a superuser can change the ownership of a publication regardless of these restrictions\&. +.PP +Adding/Setting any schema when the publication also publishes a table with a column list, and vice versa is not supported\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing publication whose definition is to be altered\&. +.RE +.PP +\fItable_name\fR +.RS 4 +Name of an existing table\&. If +ONLY +is specified before the table name, only that table is affected\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are affected\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.sp +Optionally, a column list can be specified\&. See +CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)) +for details\&. Note that a subscription having several publications in which the same table has been published with different column lists is not supported\&. See +Warning: Combining Column Lists from Multiple Publications +for details of potential problems when altering column lists\&. +.sp +If the optional +WHERE +clause is specified, rows for which the +\fIexpression\fR +evaluates to false or null will not be published\&. Note that parentheses are required around the expression\&. The +\fIexpression\fR +is evaluated with the role used for the replication connection\&. +.RE +.PP +\fIschema_name\fR +.RS 4 +Name of an existing schema\&. +.RE +.PP +SET ( \fIpublication_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause alters publication parameters originally set by +CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7))\&. See there for more information\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the publication\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the publication\&. +.RE +.SH "EXAMPLES" +.PP +Change the publication to publish only deletes and updates: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PUBLICATION noinsert SET (publish = \*(Aqupdate, delete\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Add some tables to the publication: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PUBLICATION mypublication ADD TABLE users (user_id, firstname), departments; +.fi +.if n \{\ +.RE +.\} +.PP +Change the set of columns published for a table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PUBLICATION mypublication SET TABLE users (user_id, firstname, lastname), TABLE departments; +.fi +.if n \{\ +.RE +.\} +.PP +Add schemas +marketing +and +sales +to the publication +sales_publication: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PUBLICATION sales_publication ADD TABLES IN SCHEMA marketing, sales; +.fi +.if n \{\ +.RE +.\} +.PP +Add tables +users, +departments +and schema +production +to the publication +production_publication: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER PUBLICATION production_publication ADD TABLE users, departments, TABLES IN SCHEMA production; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER PUBLICATION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)), DROP PUBLICATION (\fBDROP_PUBLICATION\fR(7)), CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)), ALTER SUBSCRIPTION (\fBALTER_SUBSCRIPTION\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_ROLE.7 b/doc/src/sgml/man7/ALTER_ROLE.7 new file mode 100644 index 0000000..3183de0 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_ROLE.7 @@ -0,0 +1,335 @@ +'\" t +.\" Title: ALTER ROLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER ROLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_ROLE \- change a database role +.SH "SYNOPSIS" +.sp +.nf +ALTER ROLE \fIrole_specification\fR [ WITH ] \fIoption\fR [ \&.\&.\&. ] + +where \fIoption\fR can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | REPLICATION | NOREPLICATION + | BYPASSRLS | NOBYPASSRLS + | CONNECTION LIMIT \fIconnlimit\fR + | [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq | PASSWORD NULL + | VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq + +ALTER ROLE \fIname\fR RENAME TO \fInew_name\fR + +ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT } +ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] SET \fIconfiguration_parameter\fR FROM CURRENT +ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] RESET \fIconfiguration_parameter\fR +ALTER ROLE { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] RESET ALL + +where \fIrole_specification\fR can be: + + \fIrole_name\fR + | CURRENT_ROLE + | CURRENT_USER + | SESSION_USER +.fi +.SH "DESCRIPTION" +.PP +\fBALTER ROLE\fR +changes the attributes of a +PostgreSQL +role\&. +.PP +The first variant of this command listed in the synopsis can change many of the role attributes that can be specified in +\fBCREATE ROLE\fR\&. (All the possible attributes are covered, except that there are no options for adding or removing memberships; use +\fBGRANT\fR +and +\fBREVOKE\fR +for that\&.) Attributes not mentioned in the command retain their previous settings\&. Database superusers can change any of these settings for any role\&. Roles having +CREATEROLE +privilege can change any of these settings except +SUPERUSER, +REPLICATION, and +BYPASSRLS; but only for non\-superuser and non\-replication roles\&. Ordinary roles can only change their own password\&. +.PP +The second variant changes the name of the role\&. Database superusers can rename any role\&. Roles having +CREATEROLE +privilege can rename non\-superuser roles\&. The current session user cannot be renamed\&. (Connect as a different user if you need to do that\&.) Because +MD5\-encrypted passwords use the role name as cryptographic salt, renaming a role clears its password if the password is +MD5\-encrypted\&. +.PP +The remaining variants change a role\*(Aqs session default for a configuration variable, either for all databases or, when the +IN DATABASE +clause is specified, only for sessions in the named database\&. If +ALL +is specified instead of a role name, this changes the setting for all roles\&. Using +ALL +with +IN DATABASE +is effectively the same as using the command +ALTER DATABASE \&.\&.\&. SET \&.\&.\&.\&. +.PP +Whenever the role subsequently starts a new session, the specified value becomes the session default, overriding whatever setting is present in +postgresql\&.conf +or has been received from the +\fBpostgres\fR +command line\&. This only happens at login time; executing +\fBSET ROLE\fR +or +\fBSET SESSION AUTHORIZATION\fR +does not cause new configuration values to be set\&. Settings set for all databases are overridden by database\-specific settings attached to a role\&. Settings for specific databases or specific roles override settings for all roles\&. +.PP +Superusers can change anyone\*(Aqs session defaults\&. Roles having +CREATEROLE +privilege can change defaults for non\-superuser roles\&. Ordinary roles can only set defaults for themselves\&. Certain configuration variables cannot be set this way, or can only be set if a superuser issues the command\&. Only superusers can change a setting for all roles in all databases\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the role whose attributes are to be altered\&. +.RE +.PP +CURRENT_ROLE +.br +CURRENT_USER +.RS 4 +Alter the current user instead of an explicitly identified role\&. +.RE +.PP +SESSION_USER +.RS 4 +Alter the current session user instead of an explicitly identified role\&. +.RE +.PP +SUPERUSER +.br +NOSUPERUSER +.br +CREATEDB +.br +NOCREATEDB +.br +CREATEROLE +.br +NOCREATEROLE +.br +INHERIT +.br +NOINHERIT +.br +LOGIN +.br +NOLOGIN +.br +REPLICATION +.br +NOREPLICATION +.br +BYPASSRLS +.br +NOBYPASSRLS +.br +CONNECTION LIMIT \fIconnlimit\fR +.br +[ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq +.br +PASSWORD NULL +.br +VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq +.RS 4 +These clauses alter attributes originally set by +\fBCREATE ROLE\fR\&. For more information, see the +\fBCREATE ROLE\fR +reference page\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the role\&. +.RE +.PP +\fIdatabase_name\fR +.RS 4 +The name of the database the configuration variable should be set in\&. +.RE +.PP +\fIconfiguration_parameter\fR +.br +\fIvalue\fR +.RS 4 +Set this role\*(Aqs session default for the specified configuration parameter to the given value\&. If +\fIvalue\fR +is +DEFAULT +or, equivalently, +RESET +is used, the role\-specific variable setting is removed, so the role will inherit the system\-wide default setting in new sessions\&. Use +RESET ALL +to clear all role\-specific settings\&. +SET FROM CURRENT +saves the session\*(Aqs current value of the parameter as the role\-specific value\&. If +IN DATABASE +is specified, the configuration parameter is set or removed for the given role and database only\&. +.sp +Role\-specific variable settings take effect only at login; +\fBSET ROLE\fR +and +\fBSET SESSION AUTHORIZATION\fR +do not process role\-specific variable settings\&. +.sp +See +\fBSET\fR(7) +and +Chapter\ \&20 +for more information about allowed parameter names and values\&. +.RE +.SH "NOTES" +.PP +Use +\fBCREATE ROLE\fR +to add new roles, and +\fBDROP ROLE\fR +to remove a role\&. +.PP +\fBALTER ROLE\fR +cannot change a role\*(Aqs memberships\&. Use +\fBGRANT\fR +and +\fBREVOKE\fR +to do that\&. +.PP +Caution must be exercised when specifying an unencrypted password with this command\&. The password will be transmitted to the server in cleartext, and it might also be logged in the client\*(Aqs command history or the server log\&. +\fBpsql\fR(1) +contains a command +\fB\epassword\fR +that can be used to change a role\*(Aqs password without exposing the cleartext password\&. +.PP +It is also possible to tie a session default to a specific database rather than to a role; see +ALTER DATABASE (\fBALTER_DATABASE\fR(7))\&. If there is a conflict, database\-role\-specific settings override role\-specific ones, which in turn override database\-specific ones\&. +.SH "EXAMPLES" +.PP +Change a role\*(Aqs password: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE davide WITH PASSWORD \*(Aqhu8jmn3\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Remove a role\*(Aqs password: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE davide WITH PASSWORD NULL; +.fi +.if n \{\ +.RE +.\} +.PP +Change a password expiration date, specifying that the password should expire at midday on 4th May 2015 using the time zone which is one hour ahead of +UTC: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE chris VALID UNTIL \*(AqMay 4 12:00:00 2015 +1\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Make a password valid forever: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE fred VALID UNTIL \*(Aqinfinity\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Give a role the ability to manage other roles and create new databases: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE miriam CREATEROLE CREATEDB; +.fi +.if n \{\ +.RE +.\} +.PP +Give a role a non\-default setting of the +maintenance_work_mem +parameter: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE worker_bee SET maintenance_work_mem = 100000; +.fi +.if n \{\ +.RE +.\} +.PP +Give a role a non\-default, database\-specific setting of the +client_min_messages +parameter: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROLE fred IN DATABASE devel SET client_min_messages = DEBUG; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBALTER ROLE\fR +statement is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE ROLE (\fBCREATE_ROLE\fR(7)), DROP ROLE (\fBDROP_ROLE\fR(7)), ALTER DATABASE (\fBALTER_DATABASE\fR(7)), \fBSET\fR(7) diff --git a/doc/src/sgml/man7/ALTER_ROUTINE.7 b/doc/src/sgml/man7/ALTER_ROUTINE.7 new file mode 100644 index 0000000..ba5ff03 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_ROUTINE.7 @@ -0,0 +1,105 @@ +'\" t +.\" Title: ALTER ROUTINE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER ROUTINE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_ROUTINE \- change the definition of a routine +.SH "SYNOPSIS" +.sp +.nf +ALTER ROUTINE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + \fIaction\fR [ \&.\&.\&. ] [ RESTRICT ] +ALTER ROUTINE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + RENAME TO \fInew_name\fR +ALTER ROUTINE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER ROUTINE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + SET SCHEMA \fInew_schema\fR +ALTER ROUTINE \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] + [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR + +where \fIaction\fR is one of: + + IMMUTABLE | STABLE | VOLATILE + [ NOT ] LEAKPROOF + [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER + PARALLEL { UNSAFE | RESTRICTED | SAFE } + COST \fIexecution_cost\fR + ROWS \fIresult_rows\fR + SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT } + SET \fIconfiguration_parameter\fR FROM CURRENT + RESET \fIconfiguration_parameter\fR + RESET ALL +.fi +.SH "DESCRIPTION" +.PP +\fBALTER ROUTINE\fR +changes the definition of a routine, which can be an aggregate function, a normal function, or a procedure\&. See under +ALTER AGGREGATE (\fBALTER_AGGREGATE\fR(7)), +ALTER FUNCTION (\fBALTER_FUNCTION\fR(7)), and +ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)) +for the description of the parameters, more examples, and further details\&. +.SH "EXAMPLES" +.PP +To rename the routine +foo +for type +integer +to +foobar: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER ROUTINE foo(integer) RENAME TO foobar; +.fi +.if n \{\ +.RE +.\} +.sp +This command will work independent of whether +foo +is an aggregate, function, or procedure\&. +.SH "COMPATIBILITY" +.PP +This statement is partially compatible with the +\fBALTER ROUTINE\fR +statement in the SQL standard\&. See under +ALTER FUNCTION (\fBALTER_FUNCTION\fR(7)) +and +ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)) +for more details\&. Allowing routine names to refer to aggregate functions is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER AGGREGATE (\fBALTER_AGGREGATE\fR(7)), ALTER FUNCTION (\fBALTER_FUNCTION\fR(7)), ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)), DROP ROUTINE (\fBDROP_ROUTINE\fR(7)) +.PP +Note that there is no +CREATE ROUTINE +command\&. diff --git a/doc/src/sgml/man7/ALTER_RULE.7 b/doc/src/sgml/man7/ALTER_RULE.7 new file mode 100644 index 0000000..9f3d4e2 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_RULE.7 @@ -0,0 +1,80 @@ +'\" t +.\" Title: ALTER RULE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER RULE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_RULE \- change the definition of a rule +.SH "SYNOPSIS" +.sp +.nf +ALTER RULE \fIname\fR ON \fItable_name\fR RENAME TO \fInew_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER RULE\fR +changes properties of an existing rule\&. Currently, the only available action is to change the rule\*(Aqs name\&. +.PP +To use +\fBALTER RULE\fR, you must own the table or view that the rule applies to\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing rule to alter\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table or view that the rule applies to\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the rule\&. +.RE +.SH "EXAMPLES" +.PP +To rename an existing rule: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER RULE notify_all ON emp RENAME TO notify_me; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER RULE\fR +is a +PostgreSQL +language extension, as is the entire query rewrite system\&. +.SH "SEE ALSO" +CREATE RULE (\fBCREATE_RULE\fR(7)), DROP RULE (\fBDROP_RULE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_SCHEMA.7 b/doc/src/sgml/man7/ALTER_SCHEMA.7 new file mode 100644 index 0000000..c19a474 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_SCHEMA.7 @@ -0,0 +1,72 @@ +'\" t +.\" Title: ALTER SCHEMA +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER SCHEMA" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_SCHEMA \- change the definition of a schema +.SH "SYNOPSIS" +.sp +.nf +ALTER SCHEMA \fIname\fR RENAME TO \fInew_name\fR +ALTER SCHEMA \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +.fi +.SH "DESCRIPTION" +.PP +\fBALTER SCHEMA\fR +changes the definition of a schema\&. +.PP +You must own the schema to use +\fBALTER SCHEMA\fR\&. To rename a schema you must also have the +CREATE +privilege for the database\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and you must have the +CREATE +privilege for the database\&. (Note that superusers have all these privileges automatically\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing schema\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the schema\&. The new name cannot begin with +pg_, as such names are reserved for system schemas\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the schema\&. +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER SCHEMA\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE SCHEMA (\fBCREATE_SCHEMA\fR(7)), DROP SCHEMA (\fBDROP_SCHEMA\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_SEQUENCE.7 b/doc/src/sgml/man7/ALTER_SEQUENCE.7 new file mode 100644 index 0000000..eb474c5 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_SEQUENCE.7 @@ -0,0 +1,282 @@ +'\" t +.\" Title: ALTER SEQUENCE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER SEQUENCE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_SEQUENCE \- change the definition of a sequence generator +.SH "SYNOPSIS" +.sp +.nf +ALTER SEQUENCE [ IF EXISTS ] \fIname\fR + [ AS \fIdata_type\fR ] + [ INCREMENT [ BY ] \fIincrement\fR ] + [ MINVALUE \fIminvalue\fR | NO MINVALUE ] [ MAXVALUE \fImaxvalue\fR | NO MAXVALUE ] + [ START [ WITH ] \fIstart\fR ] + [ RESTART [ [ WITH ] \fIrestart\fR ] ] + [ CACHE \fIcache\fR ] [ [ NO ] CYCLE ] + [ OWNED BY { \fItable_name\fR\&.\fIcolumn_name\fR | NONE } ] +ALTER SEQUENCE [ IF EXISTS ] \fIname\fR SET { LOGGED | UNLOGGED } +ALTER SEQUENCE [ IF EXISTS ] \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER SEQUENCE [ IF EXISTS ] \fIname\fR RENAME TO \fInew_name\fR +ALTER SEQUENCE [ IF EXISTS ] \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER SEQUENCE\fR +changes the parameters of an existing sequence generator\&. Any parameters not specifically set in the +\fBALTER SEQUENCE\fR +command retain their prior settings\&. +.PP +You must own the sequence to use +\fBALTER SEQUENCE\fR\&. To change a sequence\*(Aqs schema, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the sequence\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the sequence\&. However, a superuser can alter ownership of any sequence anyway\&.) +.SH "PARAMETERS" +.PP +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of a sequence to be altered\&. +.RE +.PP +IF EXISTS +.RS 4 +Do not throw an error if the sequence does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The optional clause +AS \fIdata_type\fR +changes the data type of the sequence\&. Valid types are +smallint, +integer, and +bigint\&. +.sp +Changing the data type automatically changes the minimum and maximum values of the sequence if and only if the previous minimum and maximum values were the minimum or maximum value of the old data type (in other words, if the sequence had been created using +NO MINVALUE +or +NO MAXVALUE, implicitly or explicitly)\&. Otherwise, the minimum and maximum values are preserved, unless new values are given as part of the same command\&. If the minimum and maximum values do not fit into the new data type, an error will be generated\&. +.RE +.PP +\fIincrement\fR +.RS 4 +The clause +INCREMENT BY \fIincrement\fR +is optional\&. A positive value will make an ascending sequence, a negative one a descending sequence\&. If unspecified, the old increment value will be maintained\&. +.RE +.PP +\fIminvalue\fR +.br +NO MINVALUE +.RS 4 +The optional clause +MINVALUE \fIminvalue\fR +determines the minimum value a sequence can generate\&. If +NO MINVALUE +is specified, the defaults of 1 and the minimum value of the data type for ascending and descending sequences, respectively, will be used\&. If neither option is specified, the current minimum value will be maintained\&. +.RE +.PP +\fImaxvalue\fR +.br +NO MAXVALUE +.RS 4 +The optional clause +MAXVALUE \fImaxvalue\fR +determines the maximum value for the sequence\&. If +NO MAXVALUE +is specified, the defaults of the maximum value of the data type and \-1 for ascending and descending sequences, respectively, will be used\&. If neither option is specified, the current maximum value will be maintained\&. +.RE +.PP +\fIstart\fR +.RS 4 +The optional clause +START WITH \fIstart\fR +changes the recorded start value of the sequence\&. This has no effect on the +\fIcurrent\fR +sequence value; it simply sets the value that future +\fBALTER SEQUENCE RESTART\fR +commands will use\&. +.RE +.PP +\fIrestart\fR +.RS 4 +The optional clause +RESTART [ WITH \fIrestart\fR ] +changes the current value of the sequence\&. This is similar to calling the +\fBsetval\fR +function with +is_called += +false: the specified value will be returned by the +\fInext\fR +call of +\fBnextval\fR\&. Writing +RESTART +with no +\fIrestart\fR +value is equivalent to supplying the start value that was recorded by +\fBCREATE SEQUENCE\fR +or last set by +\fBALTER SEQUENCE START WITH\fR\&. +.sp +In contrast to a +\fBsetval\fR +call, a +RESTART +operation on a sequence is transactional and blocks concurrent transactions from obtaining numbers from the same sequence\&. If that\*(Aqs not the desired mode of operation, +\fBsetval\fR +should be used\&. +.RE +.PP +\fIcache\fR +.RS 4 +The clause +CACHE \fIcache\fR +enables sequence numbers to be preallocated and stored in memory for faster access\&. The minimum value is 1 (only one value can be generated at a time, i\&.e\&., no cache)\&. If unspecified, the old cache value will be maintained\&. +.RE +.PP +CYCLE +.RS 4 +The optional +CYCLE +key word can be used to enable the sequence to wrap around when the +\fImaxvalue\fR +or +\fIminvalue\fR +has been reached by an ascending or descending sequence respectively\&. If the limit is reached, the next number generated will be the +\fIminvalue\fR +or +\fImaxvalue\fR, respectively\&. +.RE +.PP +NO CYCLE +.RS 4 +If the optional +NO CYCLE +key word is specified, any calls to +\fBnextval\fR +after the sequence has reached its maximum value will return an error\&. If neither +CYCLE +or +NO CYCLE +are specified, the old cycle behavior will be maintained\&. +.RE +.PP +SET { LOGGED | UNLOGGED } +.RS 4 +This form changes the sequence from unlogged to logged or vice\-versa (see +CREATE SEQUENCE (\fBCREATE_SEQUENCE\fR(7)))\&. It cannot be applied to a temporary sequence\&. +.RE +.PP +OWNED BY \fItable_name\fR\&.\fIcolumn_name\fR +.br +OWNED BY NONE +.RS 4 +The +OWNED BY +option causes the sequence to be associated with a specific table column, such that if that column (or its whole table) is dropped, the sequence will be automatically dropped as well\&. If specified, this association replaces any previously specified association for the sequence\&. The specified table must have the same owner and be in the same schema as the sequence\&. Specifying +OWNED BY NONE +removes any existing association, making the sequence +\(lqfree\-standing\(rq\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the sequence\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the sequence\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the sequence\&. +.RE +.SH "NOTES" +.PP +\fBALTER SEQUENCE\fR +will not immediately affect +\fBnextval\fR +results in backends, other than the current one, that have preallocated (cached) sequence values\&. They will use up all cached values prior to noticing the changed sequence generation parameters\&. The current backend will be affected immediately\&. +.PP +\fBALTER SEQUENCE\fR +does not affect the +\fBcurrval\fR +status for the sequence\&. (Before +PostgreSQL +8\&.3, it sometimes did\&.) +.PP +\fBALTER SEQUENCE\fR +blocks concurrent +\fBnextval\fR, +\fBcurrval\fR, +\fBlastval\fR, and +\fBsetval\fR +calls\&. +.PP +For historical reasons, +\fBALTER TABLE\fR +can be used with sequences too; but the only variants of +\fBALTER TABLE\fR +that are allowed with sequences are equivalent to the forms shown above\&. +.SH "EXAMPLES" +.PP +Restart a sequence called +serial, at 105: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SEQUENCE serial RESTART WITH 105; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER SEQUENCE\fR +conforms to the +SQL +standard, except for the +AS, +START WITH, +OWNED BY, +OWNER TO, +RENAME TO, and +SET SCHEMA +clauses, which are +PostgreSQL +extensions\&. +.SH "SEE ALSO" +CREATE SEQUENCE (\fBCREATE_SEQUENCE\fR(7)), DROP SEQUENCE (\fBDROP_SEQUENCE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_SERVER.7 b/doc/src/sgml/man7/ALTER_SERVER.7 new file mode 100644 index 0000000..c087300 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_SERVER.7 @@ -0,0 +1,118 @@ +'\" t +.\" Title: ALTER SERVER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER SERVER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_SERVER \- change the definition of a foreign server +.SH "SYNOPSIS" +.sp +.nf +ALTER SERVER \fIname\fR [ VERSION \*(Aq\fInew_version\fR\*(Aq ] + [ OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] ) ] +ALTER SERVER \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER SERVER \fIname\fR RENAME TO \fInew_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER SERVER\fR +changes the definition of a foreign server\&. The first form changes the server version string or the generic options of the server (at least one clause is required)\&. The second form changes the owner of the server\&. +.PP +To alter the server you must be the owner of the server\&. Additionally to alter the owner, you must own the server and also be a direct or indirect member of the new owning role, and you must have +USAGE +privilege on the server\*(Aqs foreign\-data wrapper\&. (Note that superusers satisfy all these criteria automatically\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing server\&. +.RE +.PP +\fInew_version\fR +.RS 4 +New server version\&. +.RE +.PP +OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] ) +.RS 4 +Change options for the server\&. +ADD, +SET, and +DROP +specify the action to be performed\&. +ADD +is assumed if no operation is explicitly specified\&. Option names must be unique; names and values are also validated using the server\*(Aqs foreign\-data wrapper library\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the foreign server\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the foreign server\&. +.RE +.SH "EXAMPLES" +.PP +Alter server +foo, add connection options: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SERVER foo OPTIONS (host \*(Aqfoo\*(Aq, dbname \*(Aqfoodb\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Alter server +foo, change version, change +host +option: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SERVER foo VERSION \*(Aq8\&.4\*(Aq OPTIONS (SET host \*(Aqbaz\*(Aq); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER SERVER\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. The +OWNER TO +and +RENAME +forms are PostgreSQL extensions\&. +.SH "SEE ALSO" +CREATE SERVER (\fBCREATE_SERVER\fR(7)), DROP SERVER (\fBDROP_SERVER\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_STATISTICS.7 b/doc/src/sgml/man7/ALTER_STATISTICS.7 new file mode 100644 index 0000000..c88a7f5 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_STATISTICS.7 @@ -0,0 +1,91 @@ +'\" t +.\" Title: ALTER STATISTICS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER STATISTICS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_STATISTICS \- change the definition of an extended statistics object +.SH "SYNOPSIS" +.sp +.nf +ALTER STATISTICS \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER STATISTICS \fIname\fR RENAME TO \fInew_name\fR +ALTER STATISTICS \fIname\fR SET SCHEMA \fInew_schema\fR +ALTER STATISTICS \fIname\fR SET STATISTICS \fInew_target\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER STATISTICS\fR +changes the parameters of an existing extended statistics object\&. Any parameters not specifically set in the +\fBALTER STATISTICS\fR +command retain their prior settings\&. +.PP +You must own the statistics object to use +\fBALTER STATISTICS\fR\&. To change a statistics object\*(Aqs schema, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the statistics object\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the statistics object\&. However, a superuser can alter ownership of any statistics object anyway\&.) +.SH "PARAMETERS" +.PP +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the statistics object to be altered\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the statistics object\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the statistics object\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the statistics object\&. +.RE +.PP +\fInew_target\fR +.RS 4 +The statistic\-gathering target for this statistics object for subsequent +\fBANALYZE\fR +operations\&. The target can be set in the range 0 to 10000; alternatively, set it to \-1 to revert to using the maximum of the statistics target of the referenced columns, if set, or the system default statistics target (default_statistics_target)\&. For more information on the use of statistics by the +PostgreSQL +query planner, refer to +Section\ \&14.2\&. +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER STATISTICS\fR +command in the SQL standard\&. +.SH "SEE ALSO" +CREATE STATISTICS (\fBCREATE_STATISTICS\fR(7)), DROP STATISTICS (\fBDROP_STATISTICS\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_SUBSCRIPTION.7 b/doc/src/sgml/man7/ALTER_SUBSCRIPTION.7 new file mode 100644 index 0000000..933f047 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_SUBSCRIPTION.7 @@ -0,0 +1,235 @@ +'\" t +.\" Title: ALTER SUBSCRIPTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER SUBSCRIPTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_SUBSCRIPTION \- change the definition of a subscription +.SH "SYNOPSIS" +.sp +.nf +ALTER SUBSCRIPTION \fIname\fR CONNECTION \*(Aq\fIconninfo\fR\*(Aq +ALTER SUBSCRIPTION \fIname\fR SET PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] [ WITH ( \fIpublication_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +ALTER SUBSCRIPTION \fIname\fR ADD PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] [ WITH ( \fIpublication_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +ALTER SUBSCRIPTION \fIname\fR DROP PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] [ WITH ( \fIpublication_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +ALTER SUBSCRIPTION \fIname\fR REFRESH PUBLICATION [ WITH ( \fIrefresh_option\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +ALTER SUBSCRIPTION \fIname\fR ENABLE +ALTER SUBSCRIPTION \fIname\fR DISABLE +ALTER SUBSCRIPTION \fIname\fR SET ( \fIsubscription_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +ALTER SUBSCRIPTION \fIname\fR SKIP ( \fIskip_option\fR = \fIvalue\fR ) +ALTER SUBSCRIPTION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER SUBSCRIPTION \fIname\fR RENAME TO \fInew_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER SUBSCRIPTION\fR +can change most of the subscription properties that can be specified in +CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))\&. +.PP +You must own the subscription to use +\fBALTER SUBSCRIPTION\fR\&. To alter the owner, you must also be a direct or indirect member of the new owning role\&. The new owner has to be a superuser\&. (Currently, all subscription owners must be superusers, so the owner checks will be bypassed in practice\&. But this might change in the future\&.) +.PP +When refreshing a publication we remove the relations that are no longer part of the publication and we also remove the table synchronization slots if there are any\&. It is necessary to remove these slots so that the resources allocated for the subscription on the remote host are released\&. If due to network breakdown or some other error, +PostgreSQL +is unable to remove the slots, an error will be reported\&. To proceed in this situation, the user either needs to retry the operation or disassociate the slot from the subscription and drop the subscription as explained in +DROP SUBSCRIPTION (\fBDROP_SUBSCRIPTION\fR(7))\&. +.PP +Commands +\fBALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION\fR +and +\fBALTER SUBSCRIPTION \&.\&.\&. {SET|ADD|DROP} PUBLICATION \&.\&.\&.\fR +with +refresh +option as +true +cannot be executed inside a transaction block\&. These commands also cannot be executed when the subscription has +two_phase +commit enabled, unless +copy_data +is +false\&. See column +subtwophasestate +of +pg_subscription +to know the actual two\-phase state\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of a subscription whose properties are to be altered\&. +.RE +.PP +CONNECTION \*(Aq\fIconninfo\fR\*(Aq +.RS 4 +This clause replaces the connection string originally set by +CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))\&. See there for more information\&. +.RE +.PP +SET PUBLICATION \fIpublication_name\fR +.br +ADD PUBLICATION \fIpublication_name\fR +.br +DROP PUBLICATION \fIpublication_name\fR +.RS 4 +These forms change the list of subscribed publications\&. +SET +replaces the entire list of publications with a new list, +ADD +adds additional publications to the list of publications, and +DROP +removes the publications from the list of publications\&. We allow non\-existent publications to be specified in +ADD +and +SET +variants so that users can add those later\&. See +CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)) +for more information\&. By default, this command will also act like +REFRESH PUBLICATION\&. +.sp +\fIpublication_option\fR +specifies additional options for this operation\&. The supported options are: +.PP +refresh (boolean) +.RS 4 +When false, the command will not try to refresh table information\&. +REFRESH PUBLICATION +should then be executed separately\&. The default is +true\&. +.RE +.sp +Additionally, the options described under +REFRESH PUBLICATION +may be specified, to control the implicit refresh operation\&. +.RE +.PP +REFRESH PUBLICATION +.RS 4 +Fetch missing table information from publisher\&. This will start replication of tables that were added to the subscribed\-to publications since +\fBCREATE SUBSCRIPTION\fR +or the last invocation of +\fBREFRESH PUBLICATION\fR\&. +.sp +\fIrefresh_option\fR +specifies additional options for the refresh operation\&. The supported options are: +.PP +copy_data (boolean) +.RS 4 +Specifies whether to copy pre\-existing data in the publications that are being subscribed to when the replication starts\&. The default is +true\&. +.sp +Previously subscribed tables are not copied, even if a table\*(Aqs row filter +WHERE +clause has since been modified\&. +.RE +.RE +.PP +ENABLE +.RS 4 +Enables a previously disabled subscription, starting the logical replication worker at the end of the transaction\&. +.RE +.PP +DISABLE +.RS 4 +Disables a running subscription, stopping the logical replication worker at the end of the transaction\&. +.RE +.PP +SET ( \fIsubscription_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause alters parameters originally set by +CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7))\&. See there for more information\&. The parameters that can be altered are +slot_name, +synchronous_commit, +binary, +streaming, and +disable_on_error\&. +.RE +.PP +SKIP ( \fIskip_option\fR = \fIvalue\fR ) +.RS 4 +Skips applying all changes of the remote transaction\&. If incoming data violates any constraints, logical replication will stop until it is resolved\&. By using the +\fBALTER SUBSCRIPTION \&.\&.\&. SKIP\fR +command, the logical replication worker skips all data modification changes within the transaction\&. This option has no effect on the transactions that are already prepared by enabling +two_phase +on subscriber\&. After the logical replication worker successfully skips the transaction or finishes a transaction, the LSN (stored in +pg_subscription\&.subskiplsn) is cleared\&. See +Section\ \&31.5 +for the details of logical replication conflicts\&. Using this command requires superuser privilege\&. +.sp +\fIskip_option\fR +specifies options for this operation\&. The supported option is: +.PP +lsn (pg_lsn) +.RS 4 +Specifies the finish LSN of the remote transaction whose changes are to be skipped by the logical replication worker\&. The finish LSN is the LSN at which the transaction is either committed or prepared\&. Skipping individual subtransactions is not supported\&. Setting +NONE +resets the LSN\&. +.RE +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the subscription\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the subscription\&. +.RE +.SH "EXAMPLES" +.PP +Change the publication subscribed by a subscription to +insert_only: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SUBSCRIPTION mysub SET PUBLICATION insert_only; +.fi +.if n \{\ +.RE +.\} +.PP +Disable (stop) the subscription: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SUBSCRIPTION mysub DISABLE; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER SUBSCRIPTION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)), DROP SUBSCRIPTION (\fBDROP_SUBSCRIPTION\fR(7)), CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)), ALTER PUBLICATION (\fBALTER_PUBLICATION\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_SYSTEM.7 b/doc/src/sgml/man7/ALTER_SYSTEM.7 new file mode 100644 index 0000000..ffc0c15 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_SYSTEM.7 @@ -0,0 +1,134 @@ +'\" t +.\" Title: ALTER SYSTEM +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER SYSTEM" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_SYSTEM \- change a server configuration parameter +.SH "SYNOPSIS" +.sp +.nf +ALTER SYSTEM SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR [, \&.\&.\&.] | DEFAULT } + +ALTER SYSTEM RESET \fIconfiguration_parameter\fR +ALTER SYSTEM RESET ALL +.fi +.SH "DESCRIPTION" +.PP +\fBALTER SYSTEM\fR +is used for changing server configuration parameters across the entire database cluster\&. It can be more convenient than the traditional method of manually editing the +postgresql\&.conf +file\&. +\fBALTER SYSTEM\fR +writes the given parameter setting to the +postgresql\&.auto\&.conf +file, which is read in addition to +postgresql\&.conf\&. Setting a parameter to +DEFAULT, or using the +\fBRESET\fR +variant, removes that configuration entry from the +postgresql\&.auto\&.conf +file\&. Use +RESET ALL +to remove all such configuration entries\&. +.PP +Values set with +\fBALTER SYSTEM\fR +will be effective after the next server configuration reload, or after the next server restart in the case of parameters that can only be changed at server start\&. A server configuration reload can be commanded by calling the SQL function +\fBpg_reload_conf()\fR, running +pg_ctl reload, or sending a +SIGHUP +signal to the main server process\&. +.PP +Only superusers and users granted +ALTER SYSTEM +privilege on a parameter can change it using +\fBALTER SYSTEM\fR\&. Also, since this command acts directly on the file system and cannot be rolled back, it is not allowed inside a transaction block or function\&. +.SH "PARAMETERS" +.PP +\fIconfiguration_parameter\fR +.RS 4 +Name of a settable configuration parameter\&. Available parameters are documented in +Chapter\ \&20\&. +.RE +.PP +\fIvalue\fR +.RS 4 +New value of the parameter\&. Values can be specified as string constants, identifiers, numbers, or comma\-separated lists of these, as appropriate for the particular parameter\&. Values that are neither numbers nor valid identifiers must be quoted\&. +DEFAULT +can be written to specify removing the parameter and its value from +postgresql\&.auto\&.conf\&. +.sp +For some list\-accepting parameters, quoted values will produce double\-quoted output to preserve whitespace and commas; for others, double\-quotes must be used inside single\-quoted strings to get this effect\&. +.RE +.SH "NOTES" +.PP +This command can\*(Aqt be used to set +data_directory, nor parameters that are not allowed in +postgresql\&.conf +(e\&.g\&., +preset options)\&. +.PP +See +Section\ \&20.1 +for other ways to set the parameters\&. +.SH "EXAMPLES" +.PP +Set the +wal_level: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SYSTEM SET wal_level = replica; +.fi +.if n \{\ +.RE +.\} +.PP +Undo that, restoring whatever setting was effective in +postgresql\&.conf: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER SYSTEM RESET wal_level; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBALTER SYSTEM\fR +statement is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +\fBSET\fR(7), \fBSHOW\fR(7) diff --git a/doc/src/sgml/man7/ALTER_TABLE.7 b/doc/src/sgml/man7/ALTER_TABLE.7 new file mode 100644 index 0000000..2893cfc --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TABLE.7 @@ -0,0 +1,1467 @@ +'\" t +.\" Title: ALTER TABLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TABLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TABLE \- change the definition of a table +.SH "SYNOPSIS" +.sp +.nf +ALTER TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ] + \fIaction\fR [, \&.\&.\&. ] +ALTER TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ] + RENAME [ COLUMN ] \fIcolumn_name\fR TO \fInew_column_name\fR +ALTER TABLE [ IF EXISTS ] [ ONLY ] \fIname\fR [ * ] + RENAME CONSTRAINT \fIconstraint_name\fR TO \fInew_constraint_name\fR +ALTER TABLE [ IF EXISTS ] \fIname\fR + RENAME TO \fInew_name\fR +ALTER TABLE [ IF EXISTS ] \fIname\fR + SET SCHEMA \fInew_schema\fR +ALTER TABLE ALL IN TABLESPACE \fIname\fR [ OWNED BY \fIrole_name\fR [, \&.\&.\&. ] ] + SET TABLESPACE \fInew_tablespace\fR [ NOWAIT ] +ALTER TABLE [ IF EXISTS ] \fIname\fR + ATTACH PARTITION \fIpartition_name\fR { FOR VALUES \fIpartition_bound_spec\fR | DEFAULT } +ALTER TABLE [ IF EXISTS ] \fIname\fR + DETACH PARTITION \fIpartition_name\fR [ CONCURRENTLY | FINALIZE ] + +where \fIaction\fR is one of: + + ADD [ COLUMN ] [ IF NOT EXISTS ] \fIcolumn_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + DROP [ COLUMN ] [ IF EXISTS ] \fIcolumn_name\fR [ RESTRICT | CASCADE ] + ALTER [ COLUMN ] \fIcolumn_name\fR [ SET DATA ] TYPE \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ USING \fIexpression\fR ] + ALTER [ COLUMN ] \fIcolumn_name\fR SET DEFAULT \fIexpression\fR + ALTER [ COLUMN ] \fIcolumn_name\fR DROP DEFAULT + ALTER [ COLUMN ] \fIcolumn_name\fR { SET | DROP } NOT NULL + ALTER [ COLUMN ] \fIcolumn_name\fR DROP EXPRESSION [ IF EXISTS ] + ALTER [ COLUMN ] \fIcolumn_name\fR ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( \fIsequence_options\fR ) ] + ALTER [ COLUMN ] \fIcolumn_name\fR { SET GENERATED { ALWAYS | BY DEFAULT } | SET \fIsequence_option\fR | RESTART [ [ WITH ] \fIrestart\fR ] } [\&.\&.\&.] + ALTER [ COLUMN ] \fIcolumn_name\fR DROP IDENTITY [ IF EXISTS ] + ALTER [ COLUMN ] \fIcolumn_name\fR SET STATISTICS \fIinteger\fR + ALTER [ COLUMN ] \fIcolumn_name\fR SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) + ALTER [ COLUMN ] \fIcolumn_name\fR RESET ( \fIattribute_option\fR [, \&.\&.\&. ] ) + ALTER [ COLUMN ] \fIcolumn_name\fR SET STORAGE { PLAIN | EXTERNAL | EXTENDED | MAIN } + ALTER [ COLUMN ] \fIcolumn_name\fR SET COMPRESSION \fIcompression_method\fR + ADD \fItable_constraint\fR [ NOT VALID ] + ADD \fItable_constraint_using_index\fR + ALTER CONSTRAINT \fIconstraint_name\fR [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] + VALIDATE CONSTRAINT \fIconstraint_name\fR + DROP CONSTRAINT [ IF EXISTS ] \fIconstraint_name\fR [ RESTRICT | CASCADE ] + DISABLE TRIGGER [ \fItrigger_name\fR | ALL | USER ] + ENABLE TRIGGER [ \fItrigger_name\fR | ALL | USER ] + ENABLE REPLICA TRIGGER \fItrigger_name\fR + ENABLE ALWAYS TRIGGER \fItrigger_name\fR + DISABLE RULE \fIrewrite_rule_name\fR + ENABLE RULE \fIrewrite_rule_name\fR + ENABLE REPLICA RULE \fIrewrite_rule_name\fR + ENABLE ALWAYS RULE \fIrewrite_rule_name\fR + DISABLE ROW LEVEL SECURITY + ENABLE ROW LEVEL SECURITY + FORCE ROW LEVEL SECURITY + NO FORCE ROW LEVEL SECURITY + CLUSTER ON \fIindex_name\fR + SET WITHOUT CLUSTER + SET WITHOUT OIDS + SET ACCESS METHOD \fInew_access_method\fR + SET TABLESPACE \fInew_tablespace\fR + SET { LOGGED | UNLOGGED } + SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) + RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] ) + INHERIT \fIparent_table\fR + NO INHERIT \fIparent_table\fR + OF \fItype_name\fR + NOT OF + OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } + REPLICA IDENTITY { DEFAULT | USING INDEX \fIindex_name\fR | FULL | NOTHING } + +and \fIpartition_bound_spec\fR is: + +IN ( \fIpartition_bound_expr\fR [, \&.\&.\&.] ) | +FROM ( { \fIpartition_bound_expr\fR | MINVALUE | MAXVALUE } [, \&.\&.\&.] ) + TO ( { \fIpartition_bound_expr\fR | MINVALUE | MAXVALUE } [, \&.\&.\&.] ) | +WITH ( MODULUS \fInumeric_literal\fR, REMAINDER \fInumeric_literal\fR ) + +and \fIcolumn_constraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +{ NOT NULL | + NULL | + CHECK ( \fIexpression\fR ) [ NO INHERIT ] | + DEFAULT \fIdefault_expr\fR | + GENERATED ALWAYS AS ( \fIgeneration_expr\fR ) STORED | + GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( \fIsequence_options\fR ) ] | + UNIQUE [ NULLS [ NOT ] DISTINCT ] \fIindex_parameters\fR | + PRIMARY KEY \fIindex_parameters\fR | + REFERENCES \fIreftable\fR [ ( \fIrefcolumn\fR ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] + [ ON DELETE \fIreferential_action\fR ] [ ON UPDATE \fIreferential_action\fR ] } +[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] + +and \fItable_constraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +{ CHECK ( \fIexpression\fR ) [ NO INHERIT ] | + UNIQUE [ NULLS [ NOT ] DISTINCT ] ( \fIcolumn_name\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR | + PRIMARY KEY ( \fIcolumn_name\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR | + EXCLUDE [ USING \fIindex_method\fR ] ( \fIexclude_element\fR WITH \fIoperator\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR [ WHERE ( \fIpredicate\fR ) ] | + FOREIGN KEY ( \fIcolumn_name\fR [, \&.\&.\&. ] ) REFERENCES \fIreftable\fR [ ( \fIrefcolumn\fR [, \&.\&.\&. ] ) ] + [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE \fIreferential_action\fR ] [ ON UPDATE \fIreferential_action\fR ] } +[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] + +and \fItable_constraint_using_index\fR is: + + [ CONSTRAINT \fIconstraint_name\fR ] + { UNIQUE | PRIMARY KEY } USING INDEX \fIindex_name\fR + [ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] + +\fIindex_parameters\fR in UNIQUE, PRIMARY KEY, and EXCLUDE constraints are: + +[ INCLUDE ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] +[ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +[ USING INDEX TABLESPACE \fItablespace_name\fR ] + +\fIexclude_element\fR in an EXCLUDE constraint is: + +{ \fIcolumn_name\fR | ( \fIexpression\fR ) } [ \fIopclass\fR ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] + +\fIreferential_action\fR in a FOREIGN KEY/REFERENCES constraint is: + +{ NO ACTION | RESTRICT | CASCADE | SET NULL [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] | SET DEFAULT [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] } +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TABLE\fR +changes the definition of an existing table\&. There are several subforms described below\&. Note that the lock level required may differ for each subform\&. An +ACCESS EXCLUSIVE +lock is acquired unless explicitly noted\&. When multiple subcommands are given, the lock acquired will be the strictest one required by any subcommand\&. +.PP +ADD COLUMN [ IF NOT EXISTS ] +.RS 4 +This form adds a new column to the table, using the same syntax as +\fBCREATE TABLE\fR\&. If +IF NOT EXISTS +is specified and a column already exists with this name, no error is thrown\&. +.RE +.PP +DROP COLUMN [ IF EXISTS ] +.RS 4 +This form drops a column from a table\&. Indexes and table constraints involving the column will be automatically dropped as well\&. Multivariate statistics referencing the dropped column will also be removed if the removal of the column would cause the statistics to contain data for only a single column\&. You will need to say +CASCADE +if anything outside the table depends on the column, for example, foreign key references or views\&. If +IF EXISTS +is specified and the column does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +SET DATA TYPE +.RS 4 +This form changes the type of a column of a table\&. Indexes and simple table constraints involving the column will be automatically converted to use the new column type by reparsing the originally supplied expression\&. The optional +COLLATE +clause specifies a collation for the new column; if omitted, the collation is the default for the new column type\&. The optional +USING +clause specifies how to compute the new column value from the old; if omitted, the default conversion is the same as an assignment cast from old data type to new\&. A +USING +clause must be provided if there is no implicit or assignment cast from old to new type\&. +.sp +When this form is used, the column\*(Aqs statistics are removed, so running +\fBANALYZE\fR +on the table afterwards is recommended\&. +.RE +.PP +SET/DROP DEFAULT +.RS 4 +These forms set or remove the default value for a column (where removal is equivalent to setting the default value to NULL)\&. The new default value will only apply in subsequent +\fBINSERT\fR +or +\fBUPDATE\fR +commands; it does not cause rows already in the table to change\&. +.RE +.PP +SET/DROP NOT NULL +.RS 4 +These forms change whether a column is marked to allow null values or to reject null values\&. +.sp +SET NOT NULL +may only be applied to a column provided none of the records in the table contain a +NULL +value for the column\&. Ordinarily this is checked during the +ALTER TABLE +by scanning the entire table; however, if a valid +CHECK +constraint is found which proves no +NULL +can exist, then the table scan is skipped\&. +.sp +If this table is a partition, one cannot perform +DROP NOT NULL +on a column if it is marked +NOT NULL +in the parent table\&. To drop the +NOT NULL +constraint from all the partitions, perform +DROP NOT NULL +on the parent table\&. Even if there is no +NOT NULL +constraint on the parent, such a constraint can still be added to individual partitions, if desired; that is, the children can disallow nulls even if the parent allows them, but not the other way around\&. +.RE +.PP +DROP EXPRESSION [ IF EXISTS ] +.RS 4 +This form turns a stored generated column into a normal base column\&. Existing data in the columns is retained, but future changes will no longer apply the generation expression\&. +.sp +If +DROP EXPRESSION IF EXISTS +is specified and the column is not a stored generated column, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +ADD GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY +.br +SET GENERATED { ALWAYS | BY DEFAULT } +.br +DROP IDENTITY [ IF EXISTS ] +.RS 4 +These forms change whether a column is an identity column or change the generation attribute of an existing identity column\&. See +\fBCREATE TABLE\fR +for details\&. Like +SET DEFAULT, these forms only affect the behavior of subsequent +\fBINSERT\fR +and +\fBUPDATE\fR +commands; they do not cause rows already in the table to change\&. +.sp +If +DROP IDENTITY IF EXISTS +is specified and the column is not an identity column, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +SET \fIsequence_option\fR +.br +RESTART +.RS 4 +These forms alter the sequence that underlies an existing identity column\&. +\fIsequence_option\fR +is an option supported by +\fBALTER SEQUENCE\fR +such as +INCREMENT BY\&. +.RE +.PP +SET STATISTICS +.RS 4 +This form sets the per\-column statistics\-gathering target for subsequent +\fBANALYZE\fR +operations\&. The target can be set in the range 0 to 10000; alternatively, set it to \-1 to revert to using the system default statistics target (default_statistics_target)\&. For more information on the use of statistics by the +PostgreSQL +query planner, refer to +Section\ \&14.2\&. +.sp +SET STATISTICS +acquires a +SHARE UPDATE EXCLUSIVE +lock\&. +.RE +.PP +SET ( \fIattribute_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) +.br +RESET ( \fIattribute_option\fR [, \&.\&.\&. ] ) +.RS 4 +This form sets or resets per\-attribute options\&. Currently, the only defined per\-attribute options are +n_distinct +and +n_distinct_inherited, which override the number\-of\-distinct\-values estimates made by subsequent +\fBANALYZE\fR +operations\&. +n_distinct +affects the statistics for the table itself, while +n_distinct_inherited +affects the statistics gathered for the table plus its inheritance children\&. When set to a positive value, +\fBANALYZE\fR +will assume that the column contains exactly the specified number of distinct nonnull values\&. When set to a negative value, which must be greater than or equal to \-1, +\fBANALYZE\fR +will assume that the number of distinct nonnull values in the column is linear in the size of the table; the exact count is to be computed by multiplying the estimated table size by the absolute value of the given number\&. For example, a value of \-1 implies that all values in the column are distinct, while a value of \-0\&.5 implies that each value appears twice on the average\&. This can be useful when the size of the table changes over time, since the multiplication by the number of rows in the table is not performed until query planning time\&. Specify a value of 0 to revert to estimating the number of distinct values normally\&. For more information on the use of statistics by the +PostgreSQL +query planner, refer to +Section\ \&14.2\&. +.sp +Changing per\-attribute options acquires a +SHARE UPDATE EXCLUSIVE +lock\&. +.RE +.PP +SET STORAGE +.RS 4 +This form sets the storage mode for a column\&. This controls whether this column is held inline or in a secondary +TOAST +table, and whether the data should be compressed or not\&. +PLAIN +must be used for fixed\-length values such as +integer +and is inline, uncompressed\&. +MAIN +is for inline, compressible data\&. +EXTERNAL +is for external, uncompressed data, and +EXTENDED +is for external, compressed data\&. +EXTENDED +is the default for most data types that support non\-PLAIN +storage\&. Use of +EXTERNAL +will make substring operations on very large +text +and +bytea +values run faster, at the penalty of increased storage space\&. Note that +SET STORAGE +doesn\*(Aqt itself change anything in the table, it just sets the strategy to be pursued during future table updates\&. See +Section\ \&73.2 +for more information\&. +.RE +.PP +SET COMPRESSION \fIcompression_method\fR +.RS 4 +This form sets the compression method for a column, determining how values inserted in future will be compressed (if the storage mode permits compression at all)\&. This does not cause the table to be rewritten, so existing data may still be compressed with other compression methods\&. If the table is restored with +pg_restore, then all values are rewritten with the configured compression method\&. However, when data is inserted from another relation (for example, by +\fBINSERT \&.\&.\&. SELECT\fR), values from the source table are not necessarily detoasted, so any previously compressed data may retain its existing compression method, rather than being recompressed with the compression method of the target column\&. The supported compression methods are +pglz +and +lz4\&. (lz4 +is available only if +\fB\-\-with\-lz4\fR +was used when building +PostgreSQL\&.) In addition, +\fIcompression_method\fR +can be +default, which selects the default behavior of consulting the +default_toast_compression +setting at the time of data insertion to determine the method to use\&. +.RE +.PP +ADD \fItable_constraint\fR [ NOT VALID ] +.RS 4 +This form adds a new constraint to a table using the same constraint syntax as +\fBCREATE TABLE\fR, plus the option +NOT VALID, which is currently only allowed for foreign key and CHECK constraints\&. +.sp +Normally, this form will cause a scan of the table to verify that all existing rows in the table satisfy the new constraint\&. But if the +NOT VALID +option is used, this potentially\-lengthy scan is skipped\&. The constraint will still be enforced against subsequent inserts or updates (that is, they\*(Aqll fail unless there is a matching row in the referenced table, in the case of foreign keys, or they\*(Aqll fail unless the new row matches the specified check condition)\&. But the database will not assume that the constraint holds for all rows in the table, until it is validated by using the +VALIDATE CONSTRAINT +option\&. See +Notes +below for more information about using the +NOT VALID +option\&. +.sp +Although most forms of +ADD \fItable_constraint\fR +require an +ACCESS EXCLUSIVE +lock, +ADD FOREIGN KEY +requires only a +SHARE ROW EXCLUSIVE +lock\&. Note that +ADD FOREIGN KEY +also acquires a +SHARE ROW EXCLUSIVE +lock on the referenced table, in addition to the lock on the table on which the constraint is declared\&. +.sp +Additional restrictions apply when unique or primary key constraints are added to partitioned tables; see +\fBCREATE TABLE\fR\&. Also, foreign key constraints on partitioned tables may not be declared +NOT VALID +at present\&. +.RE +.PP +ADD \fItable_constraint_using_index\fR +.RS 4 +This form adds a new +PRIMARY KEY +or +UNIQUE +constraint to a table based on an existing unique index\&. All the columns of the index will be included in the constraint\&. +.sp +The index cannot have expression columns nor be a partial index\&. Also, it must be a b\-tree index with default sort ordering\&. These restrictions ensure that the index is equivalent to one that would be built by a regular +ADD PRIMARY KEY +or +ADD UNIQUE +command\&. +.sp +If +PRIMARY KEY +is specified, and the index\*(Aqs columns are not already marked +NOT NULL, then this command will attempt to do +ALTER COLUMN SET NOT NULL +against each such column\&. That requires a full table scan to verify the column(s) contain no nulls\&. In all other cases, this is a fast operation\&. +.sp +If a constraint name is provided then the index will be renamed to match the constraint name\&. Otherwise the constraint will be named the same as the index\&. +.sp +After this command is executed, the index is +\(lqowned\(rq +by the constraint, in the same way as if the index had been built by a regular +ADD PRIMARY KEY +or +ADD UNIQUE +command\&. In particular, dropping the constraint will make the index disappear too\&. +.sp +This form is not currently supported on partitioned tables\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Adding a constraint using an existing index can be helpful in situations where a new constraint needs to be added without blocking table updates for a long time\&. To do that, create the index using +\fBCREATE INDEX CONCURRENTLY\fR, and then install it as an official constraint using this syntax\&. See the example below\&. +.sp .5v +.RE +.RE +.PP +ALTER CONSTRAINT +.RS 4 +This form alters the attributes of a constraint that was previously created\&. Currently only foreign key constraints may be altered\&. +.RE +.PP +VALIDATE CONSTRAINT +.RS 4 +This form validates a foreign key or check constraint that was previously created as +NOT VALID, by scanning the table to ensure there are no rows for which the constraint is not satisfied\&. Nothing happens if the constraint is already marked valid\&. (See +Notes +below for an explanation of the usefulness of this command\&.) +.sp +This command acquires a +SHARE UPDATE EXCLUSIVE +lock\&. +.RE +.PP +DROP CONSTRAINT [ IF EXISTS ] +.RS 4 +This form drops the specified constraint on a table, along with any index underlying the constraint\&. If +IF EXISTS +is specified and the constraint does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +DISABLE/ENABLE [ REPLICA | ALWAYS ] TRIGGER +.RS 4 +These forms configure the firing of trigger(s) belonging to the table\&. A disabled trigger is still known to the system, but is not executed when its triggering event occurs\&. (For a deferred trigger, the enable status is checked when the event occurs, not when the trigger function is actually executed\&.) One can disable or enable a single trigger specified by name, or all triggers on the table, or only user triggers (this option excludes internally generated constraint triggers, such as those that are used to implement foreign key constraints or deferrable uniqueness and exclusion constraints)\&. Disabling or enabling internally generated constraint triggers requires superuser privileges; it should be done with caution since of course the integrity of the constraint cannot be guaranteed if the triggers are not executed\&. +.sp +The trigger firing mechanism is also affected by the configuration variable +session_replication_role\&. Simply enabled triggers (the default) will fire when the replication role is +\(lqorigin\(rq +(the default) or +\(lqlocal\(rq\&. Triggers configured as +ENABLE REPLICA +will only fire if the session is in +\(lqreplica\(rq +mode, and triggers configured as +ENABLE ALWAYS +will fire regardless of the current replication role\&. +.sp +The effect of this mechanism is that in the default configuration, triggers do not fire on replicas\&. This is useful because if a trigger is used on the origin to propagate data between tables, then the replication system will also replicate the propagated data; so the trigger should not fire a second time on the replica, because that would lead to duplication\&. However, if a trigger is used for another purpose such as creating external alerts, then it might be appropriate to set it to +ENABLE ALWAYS +so that it is also fired on replicas\&. +.sp +When this command is applied to a partitioned table, the states of corresponding clone triggers in the partitions are updated too, unless +ONLY +is specified\&. +.sp +This command acquires a +SHARE ROW EXCLUSIVE +lock\&. +.RE +.PP +DISABLE/ENABLE [ REPLICA | ALWAYS ] RULE +.RS 4 +These forms configure the firing of rewrite rules belonging to the table\&. A disabled rule is still known to the system, but is not applied during query rewriting\&. The semantics are as for disabled/enabled triggers\&. This configuration is ignored for +ON SELECT +rules, which are always applied in order to keep views working even if the current session is in a non\-default replication role\&. +.sp +The rule firing mechanism is also affected by the configuration variable +session_replication_role, analogous to triggers as described above\&. +.RE +.PP +DISABLE/ENABLE ROW LEVEL SECURITY +.RS 4 +These forms control the application of row security policies belonging to the table\&. If enabled and no policies exist for the table, then a default\-deny policy is applied\&. Note that policies can exist for a table even if row\-level security is disabled\&. In this case, the policies will +\fInot\fR +be applied and the policies will be ignored\&. See also +\fBCREATE POLICY\fR\&. +.RE +.PP +NO FORCE/FORCE ROW LEVEL SECURITY +.RS 4 +These forms control the application of row security policies belonging to the table when the user is the table owner\&. If enabled, row\-level security policies will be applied when the user is the table owner\&. If disabled (the default) then row\-level security will not be applied when the user is the table owner\&. See also +\fBCREATE POLICY\fR\&. +.RE +.PP +CLUSTER ON +.RS 4 +This form selects the default index for future +\fBCLUSTER\fR +operations\&. It does not actually re\-cluster the table\&. +.sp +Changing cluster options acquires a +SHARE UPDATE EXCLUSIVE +lock\&. +.RE +.PP +SET WITHOUT CLUSTER +.RS 4 +This form removes the most recently used +\fBCLUSTER\fR +index specification from the table\&. This affects future cluster operations that don\*(Aqt specify an index\&. +.sp +Changing cluster options acquires a +SHARE UPDATE EXCLUSIVE +lock\&. +.RE +.PP +SET WITHOUT OIDS +.RS 4 +Backward\-compatible syntax for removing the +oid +system column\&. As +oid +system columns cannot be added anymore, this never has an effect\&. +.RE +.PP +SET ACCESS METHOD +.RS 4 +This form changes the access method of the table by rewriting it\&. See +Chapter\ \&63 +for more information\&. +.RE +.PP +SET TABLESPACE +.RS 4 +This form changes the table\*(Aqs tablespace to the specified tablespace and moves the data file(s) associated with the table to the new tablespace\&. Indexes on the table, if any, are not moved; but they can be moved separately with additional +SET TABLESPACE +commands\&. When applied to a partitioned table, nothing is moved, but any partitions created afterwards with +\fBCREATE TABLE PARTITION OF\fR +will use that tablespace, unless overridden by a +TABLESPACE +clause\&. +.sp +All tables in the current database in a tablespace can be moved by using the +ALL IN TABLESPACE +form, which will lock all tables to be moved first and then move each one\&. This form also supports +OWNED BY, which will only move tables owned by the roles specified\&. If the +NOWAIT +option is specified then the command will fail if it is unable to acquire all of the locks required immediately\&. Note that system catalogs are not moved by this command; use +\fBALTER DATABASE\fR +or explicit +\fBALTER TABLE\fR +invocations instead if desired\&. The +information_schema +relations are not considered part of the system catalogs and will be moved\&. See also +\fBCREATE TABLESPACE\fR\&. +.RE +.PP +SET { LOGGED | UNLOGGED } +.RS 4 +This form changes the table from unlogged to logged or vice\-versa (see +UNLOGGED)\&. It cannot be applied to a temporary table\&. +.sp +This also changes the persistence of any sequences linked to the table (for identity or serial columns)\&. However, it is also possible to change the persistence of such sequences separately\&. +.RE +.PP +SET ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This form changes one or more storage parameters for the table\&. See +Storage Parameters +in the +\fBCREATE TABLE\fR +documentation for details on the available parameters\&. Note that the table contents will not be modified immediately by this command; depending on the parameter you might need to rewrite the table to get the desired effects\&. That can be done with +\fBVACUUM FULL\fR, +\fBCLUSTER\fR +or one of the forms of +\fBALTER TABLE\fR +that forces a table rewrite\&. For planner related parameters, changes will take effect from the next time the table is locked so currently executing queries will not be affected\&. +.sp +SHARE UPDATE EXCLUSIVE +lock will be taken for fillfactor, toast and autovacuum storage parameters, as well as the planner parameter +\fIparallel_workers\fR\&. +.RE +.PP +RESET ( \fIstorage_parameter\fR [, \&.\&.\&. ] ) +.RS 4 +This form resets one or more storage parameters to their defaults\&. As with +SET, a table rewrite might be needed to update the table entirely\&. +.RE +.PP +INHERIT \fIparent_table\fR +.RS 4 +This form adds the target table as a new child of the specified parent table\&. Subsequently, queries against the parent will include records of the target table\&. To be added as a child, the target table must already contain all the same columns as the parent (it could have additional columns, too)\&. The columns must have matching data types, and if they have +NOT NULL +constraints in the parent then they must also have +NOT NULL +constraints in the child\&. +.sp +There must also be matching child\-table constraints for all +CHECK +constraints of the parent, except those marked non\-inheritable (that is, created with +ALTER TABLE \&.\&.\&. ADD CONSTRAINT \&.\&.\&. NO INHERIT) in the parent, which are ignored; all child\-table constraints matched must not be marked non\-inheritable\&. Currently +UNIQUE, +PRIMARY KEY, and +FOREIGN KEY +constraints are not considered, but this might change in the future\&. +.RE +.PP +NO INHERIT \fIparent_table\fR +.RS 4 +This form removes the target table from the list of children of the specified parent table\&. Queries against the parent table will no longer include records drawn from the target table\&. +.RE +.PP +OF \fItype_name\fR +.RS 4 +This form links the table to a composite type as though +\fBCREATE TABLE OF\fR +had formed it\&. The table\*(Aqs list of column names and types must precisely match that of the composite type\&. The table must not inherit from any other table\&. These restrictions ensure that +\fBCREATE TABLE OF\fR +would permit an equivalent table definition\&. +.RE +.PP +NOT OF +.RS 4 +This form dissociates a typed table from its type\&. +.RE +.PP +OWNER TO +.RS 4 +This form changes the owner of the table, sequence, view, materialized view, or foreign table to the specified user\&. +.RE +.PP +REPLICA IDENTITY +.RS 4 +This form changes the information which is written to the write\-ahead log to identify rows which are updated or deleted\&. In most cases, the old value of each column is only logged if it differs from the new value; however, if the old value is stored externally, it is always logged regardless of whether it changed\&. This option has no effect except when logical replication is in use\&. +.PP +DEFAULT +.RS 4 +Records the old values of the columns of the primary key, if any\&. This is the default for non\-system tables\&. +.RE +.PP +USING INDEX \fIindex_name\fR +.RS 4 +Records the old values of the columns covered by the named index, that must be unique, not partial, not deferrable, and include only columns marked +NOT NULL\&. If this index is dropped, the behavior is the same as +NOTHING\&. +.RE +.PP +FULL +.RS 4 +Records the old values of all columns in the row\&. +.RE +.PP +NOTHING +.RS 4 +Records no information about the old row\&. This is the default for system tables\&. +.RE +.RE +.PP +RENAME +.RS 4 +The +RENAME +forms change the name of a table (or an index, sequence, view, materialized view, or foreign table), the name of an individual column in a table, or the name of a constraint of the table\&. When renaming a constraint that has an underlying index, the index is renamed as well\&. There is no effect on the stored data\&. +.RE +.PP +SET SCHEMA +.RS 4 +This form moves the table into another schema\&. Associated indexes, constraints, and sequences owned by table columns are moved as well\&. +.RE +.PP +ATTACH PARTITION \fIpartition_name\fR { FOR VALUES \fIpartition_bound_spec\fR | DEFAULT } +.RS 4 +This form attaches an existing table (which might itself be partitioned) as a partition of the target table\&. The table can be attached as a partition for specific values using +FOR VALUES +or as a default partition by using +DEFAULT\&. For each index in the target table, a corresponding one will be created in the attached table; or, if an equivalent index already exists, it will be attached to the target table\*(Aqs index, as if +\fBALTER INDEX ATTACH PARTITION\fR +had been executed\&. Note that if the existing table is a foreign table, it is currently not allowed to attach the table as a partition of the target table if there are +UNIQUE +indexes on the target table\&. (See also +CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7))\&.) For each user\-defined row\-level trigger that exists in the target table, a corresponding one is created in the attached table\&. +.sp +A partition using +FOR VALUES +uses same syntax for +\fIpartition_bound_spec\fR +as +\fBCREATE TABLE\fR\&. The partition bound specification must correspond to the partitioning strategy and partition key of the target table\&. The table to be attached must have all the same columns as the target table and no more; moreover, the column types must also match\&. Also, it must have all the +NOT NULL +and +CHECK +constraints of the target table\&. Currently +FOREIGN KEY +constraints are not considered\&. +UNIQUE +and +PRIMARY KEY +constraints from the parent table will be created in the partition, if they don\*(Aqt already exist\&. If any of the +CHECK +constraints of the table being attached are marked +NO INHERIT, the command will fail; such constraints must be recreated without the +NO INHERIT +clause\&. +.sp +If the new partition is a regular table, a full table scan is performed to check that existing rows in the table do not violate the partition constraint\&. It is possible to avoid this scan by adding a valid +CHECK +constraint to the table that allows only rows satisfying the desired partition constraint before running this command\&. The +CHECK +constraint will be used to determine that the table need not be scanned to validate the partition constraint\&. This does not work, however, if any of the partition keys is an expression and the partition does not accept +NULL +values\&. If attaching a list partition that will not accept +NULL +values, also add a +NOT NULL +constraint to the partition key column, unless it\*(Aqs an expression\&. +.sp +If the new partition is a foreign table, nothing is done to verify that all the rows in the foreign table obey the partition constraint\&. (See the discussion in +CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)) +about constraints on the foreign table\&.) +.sp +When a table has a default partition, defining a new partition changes the partition constraint for the default partition\&. The default partition can\*(Aqt contain any rows that would need to be moved to the new partition, and will be scanned to verify that none are present\&. This scan, like the scan of the new partition, can be avoided if an appropriate +CHECK +constraint is present\&. Also like the scan of the new partition, it is always skipped when the default partition is a foreign table\&. +.sp +Attaching a partition acquires a +SHARE UPDATE EXCLUSIVE +lock on the parent table, in addition to the +ACCESS EXCLUSIVE +locks on the table being attached and on the default partition (if any)\&. +.sp +Further locks must also be held on all sub\-partitions if the table being attached is itself a partitioned table\&. Likewise if the default partition is itself a partitioned table\&. The locking of the sub\-partitions can be avoided by adding a +CHECK +constraint as described in +Section\ \&5.11.2.2\&. +.RE +.PP +DETACH PARTITION \fIpartition_name\fR [ CONCURRENTLY | FINALIZE ] +.RS 4 +This form detaches the specified partition of the target table\&. The detached partition continues to exist as a standalone table, but no longer has any ties to the table from which it was detached\&. Any indexes that were attached to the target table\*(Aqs indexes are detached\&. Any triggers that were created as clones of those in the target table are removed\&. +SHARE +lock is obtained on any tables that reference this partitioned table in foreign key constraints\&. +.sp +If +CONCURRENTLY +is specified, it runs using a reduced lock level to avoid blocking other sessions that might be accessing the partitioned table\&. In this mode, two transactions are used internally\&. During the first transaction, a +SHARE UPDATE EXCLUSIVE +lock is taken on both parent table and partition, and the partition is marked as undergoing detach; at that point, the transaction is committed and all other transactions using the partitioned table are waited for\&. Once all those transactions have completed, the second transaction acquires +SHARE UPDATE EXCLUSIVE +on the partitioned table and +ACCESS EXCLUSIVE +on the partition, and the detach process completes\&. A +CHECK +constraint that duplicates the partition constraint is added to the partition\&. +CONCURRENTLY +cannot be run in a transaction block and is not allowed if the partitioned table contains a default partition\&. +.sp +If +FINALIZE +is specified, a previous +DETACH CONCURRENTLY +invocation that was canceled or interrupted is completed\&. At most one partition in a partitioned table can be pending detach at a time\&. +.RE +.PP +All the forms of ALTER TABLE that act on a single table, except +RENAME, +SET SCHEMA, +ATTACH PARTITION, and +DETACH PARTITION +can be combined into a list of multiple alterations to be applied together\&. For example, it is possible to add several columns and/or alter the type of several columns in a single command\&. This is particularly useful with large tables, since only one pass over the table need be made\&. +.PP +You must own the table to use +\fBALTER TABLE\fR\&. To change the schema or tablespace of a table, you must also have +CREATE +privilege on the new schema or tablespace\&. To add the table as a new child of a parent table, you must own the parent table as well\&. Also, to attach a table as a new partition of the table, you must own the table being attached\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the table\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the table\&. However, a superuser can alter ownership of any table anyway\&.) To add a column or alter a column type or use the +OF +clause, you must also have +USAGE +privilege on the data type\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the table does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing table to alter\&. If +ONLY +is specified before the table name, only that table is altered\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are altered\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +Name of a new or existing column\&. +.RE +.PP +\fInew_column_name\fR +.RS 4 +New name for an existing column\&. +.RE +.PP +\fInew_name\fR +.RS 4 +New name for the table\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +Data type of the new column, or new data type for an existing column\&. +.RE +.PP +\fItable_constraint\fR +.RS 4 +New table constraint for the table\&. +.RE +.PP +\fIconstraint_name\fR +.RS 4 +Name of a new or existing constraint\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the dropped column or constraint (for example, views referencing the column), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the column or constraint if there are any dependent objects\&. This is the default behavior\&. +.RE +.PP +\fItrigger_name\fR +.RS 4 +Name of a single trigger to disable or enable\&. +.RE +.PP +ALL +.RS 4 +Disable or enable all triggers belonging to the table\&. (This requires superuser privilege if any of the triggers are internally generated constraint triggers, such as those that are used to implement foreign key constraints or deferrable uniqueness and exclusion constraints\&.) +.RE +.PP +USER +.RS 4 +Disable or enable all triggers belonging to the table except for internally generated constraint triggers, such as those that are used to implement foreign key constraints or deferrable uniqueness and exclusion constraints\&. +.RE +.PP +\fIindex_name\fR +.RS 4 +The name of an existing index\&. +.RE +.PP +\fIstorage_parameter\fR +.RS 4 +The name of a table storage parameter\&. +.RE +.PP +\fIvalue\fR +.RS 4 +The new value for a table storage parameter\&. This might be a number or a word depending on the parameter\&. +.RE +.PP +\fIparent_table\fR +.RS 4 +A parent table to associate or de\-associate with this table\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the table\&. +.RE +.PP +\fInew_access_method\fR +.RS 4 +The name of the access method to which the table will be converted\&. +.RE +.PP +\fInew_tablespace\fR +.RS 4 +The name of the tablespace to which the table will be moved\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The name of the schema to which the table will be moved\&. +.RE +.PP +\fIpartition_name\fR +.RS 4 +The name of the table to attach as a new partition or to detach from this table\&. +.RE +.PP +\fIpartition_bound_spec\fR +.RS 4 +The partition bound specification for a new partition\&. Refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for more details on the syntax of the same\&. +.RE +.SH "NOTES" +.PP +The key word +COLUMN +is noise and can be omitted\&. +.PP +When a column is added with +ADD COLUMN +and a non\-volatile +DEFAULT +is specified, the default is evaluated at the time of the statement and the result stored in the table\*(Aqs metadata\&. That value will be used for the column for all existing rows\&. If no +DEFAULT +is specified, NULL is used\&. In neither case is a rewrite of the table required\&. +.PP +Adding a column with a volatile +DEFAULT +or changing the type of an existing column will require the entire table and its indexes to be rewritten\&. As an exception, when changing the type of an existing column, if the +USING +clause does not change the column contents and the old type is either binary coercible to the new type or an unconstrained domain over the new type, a table rewrite is not needed\&. However, indexes must always be rebuilt unless the system can verify that the new index would be logically equivalent to the existing one\&. For example, if the collation for a column has been changed, an index rebuild is always required because the new sort order might be different\&. However, in the absence of a collation change, a column can be changed from +text +to +varchar +(or vice versa) without rebuilding the indexes because these data types sort identically\&. Table and/or index rebuilds may take a significant amount of time for a large table; and will temporarily require as much as double the disk space\&. +.PP +Adding a +CHECK +or +NOT NULL +constraint requires scanning the table to verify that existing rows meet the constraint, but does not require a table rewrite\&. +.PP +Similarly, when attaching a new partition it may be scanned to verify that existing rows meet the partition constraint\&. +.PP +The main reason for providing the option to specify multiple changes in a single +\fBALTER TABLE\fR +is that multiple table scans or rewrites can thereby be combined into a single pass over the table\&. +.PP +Scanning a large table to verify a new foreign key or check constraint can take a long time, and other updates to the table are locked out until the +\fBALTER TABLE ADD CONSTRAINT\fR +command is committed\&. The main purpose of the +NOT VALID +constraint option is to reduce the impact of adding a constraint on concurrent updates\&. With +NOT VALID, the +\fBADD CONSTRAINT\fR +command does not scan the table and can be committed immediately\&. After that, a +VALIDATE CONSTRAINT +command can be issued to verify that existing rows satisfy the constraint\&. The validation step does not need to lock out concurrent updates, since it knows that other transactions will be enforcing the constraint for rows that they insert or update; only pre\-existing rows need to be checked\&. Hence, validation acquires only a +SHARE UPDATE EXCLUSIVE +lock on the table being altered\&. (If the constraint is a foreign key then a +ROW SHARE +lock is also required on the table referenced by the constraint\&.) In addition to improving concurrency, it can be useful to use +NOT VALID +and +VALIDATE CONSTRAINT +in cases where the table is known to contain pre\-existing violations\&. Once the constraint is in place, no new violations can be inserted, and the existing problems can be corrected at leisure until +VALIDATE CONSTRAINT +finally succeeds\&. +.PP +The +DROP COLUMN +form does not physically remove the column, but simply makes it invisible to SQL operations\&. Subsequent insert and update operations in the table will store a null value for the column\&. Thus, dropping a column is quick but it will not immediately reduce the on\-disk size of your table, as the space occupied by the dropped column is not reclaimed\&. The space will be reclaimed over time as existing rows are updated\&. +.PP +To force immediate reclamation of space occupied by a dropped column, you can execute one of the forms of +\fBALTER TABLE\fR +that performs a rewrite of the whole table\&. This results in reconstructing each row with the dropped column replaced by a null value\&. +.PP +The rewriting forms of +\fBALTER TABLE\fR +are not MVCC\-safe\&. After a table rewrite, the table will appear empty to concurrent transactions, if they are using a snapshot taken before the rewrite occurred\&. See +Section\ \&13.6 +for more details\&. +.PP +The +USING +option of +SET DATA TYPE +can actually specify any expression involving the old values of the row; that is, it can refer to other columns as well as the one being converted\&. This allows very general conversions to be done with the +SET DATA TYPE +syntax\&. Because of this flexibility, the +USING +expression is not applied to the column\*(Aqs default value (if any); the result might not be a constant expression as required for a default\&. This means that when there is no implicit or assignment cast from old to new type, +SET DATA TYPE +might fail to convert the default even though a +USING +clause is supplied\&. In such cases, drop the default with +DROP DEFAULT, perform the +ALTER TYPE, and then use +SET DEFAULT +to add a suitable new default\&. Similar considerations apply to indexes and constraints involving the column\&. +.PP +If a table has any descendant tables, it is not permitted to add, rename, or change the type of a column in the parent table without doing the same to the descendants\&. This ensures that the descendants always have columns matching the parent\&. Similarly, a +CHECK +constraint cannot be renamed in the parent without also renaming it in all descendants, so that +CHECK +constraints also match between the parent and its descendants\&. (That restriction does not apply to index\-based constraints, however\&.) Also, because selecting from the parent also selects from its descendants, a constraint on the parent cannot be marked valid unless it is also marked valid for those descendants\&. In all of these cases, +\fBALTER TABLE ONLY\fR +will be rejected\&. +.PP +A recursive +DROP COLUMN +operation will remove a descendant table\*(Aqs column only if the descendant does not inherit that column from any other parents and never had an independent definition of the column\&. A nonrecursive +DROP COLUMN +(i\&.e\&., +\fBALTER TABLE ONLY \&.\&.\&. DROP COLUMN\fR) never removes any descendant columns, but instead marks them as independently defined rather than inherited\&. A nonrecursive +DROP COLUMN +command will fail for a partitioned table, because all partitions of a table must have the same columns as the partitioning root\&. +.PP +The actions for identity columns (ADD GENERATED, +SET +etc\&., +DROP IDENTITY), as well as the actions +CLUSTER, +OWNER, and +TABLESPACE +never recurse to descendant tables; that is, they always act as though +ONLY +were specified\&. Actions affecting trigger states recurse to partitions of partitioned tables (unless +ONLY +is specified), but never to traditional\-inheritance descendants\&. Adding a constraint recurses only for +CHECK +constraints that are not marked +NO INHERIT\&. +.PP +Changing any part of a system catalog table is not permitted\&. +.PP +Refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for a further description of valid parameters\&. +Chapter\ \&5 +has further information on inheritance\&. +.SH "EXAMPLES" +.PP +To add a column of type +varchar +to a table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD COLUMN address varchar(30); +.fi +.if n \{\ +.RE +.\} +.sp +That will cause all existing rows in the table to be filled with null values for the new column\&. +.PP +To add a column with a non\-null default: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE measurements + ADD COLUMN mtime timestamp with time zone DEFAULT now(); +.fi +.if n \{\ +.RE +.\} +.sp +Existing rows will be filled with the current time as the value of the new column, and then new rows will receive the time of their insertion\&. +.PP +To add a column and fill it with a value different from the default to be used later: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE transactions + ADD COLUMN status varchar(30) DEFAULT \*(Aqold\*(Aq, + ALTER COLUMN status SET default \*(Aqcurrent\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +Existing rows will be filled with +old, but then the default for subsequent commands will be +current\&. The effects are the same as if the two sub\-commands had been issued in separate +\fBALTER TABLE\fR +commands\&. +.PP +To drop a column from a table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors DROP COLUMN address RESTRICT; +.fi +.if n \{\ +.RE +.\} +.PP +To change the types of two existing columns in one operation: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors + ALTER COLUMN address TYPE varchar(80), + ALTER COLUMN name TYPE varchar(100); +.fi +.if n \{\ +.RE +.\} +.PP +To change an integer column containing Unix timestamps to +timestamp with time zone +via a +USING +clause: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE foo + ALTER COLUMN foo_timestamp SET DATA TYPE timestamp with time zone + USING + timestamp with time zone \*(Aqepoch\*(Aq + foo_timestamp * interval \*(Aq1 second\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +The same, when the column has a default expression that won\*(Aqt automatically cast to the new data type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE foo + ALTER COLUMN foo_timestamp DROP DEFAULT, + ALTER COLUMN foo_timestamp TYPE timestamp with time zone + USING + timestamp with time zone \*(Aqepoch\*(Aq + foo_timestamp * interval \*(Aq1 second\*(Aq, + ALTER COLUMN foo_timestamp SET DEFAULT now(); +.fi +.if n \{\ +.RE +.\} +.PP +To rename an existing column: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors RENAME COLUMN address TO city; +.fi +.if n \{\ +.RE +.\} +.PP +To rename an existing table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors RENAME TO suppliers; +.fi +.if n \{\ +.RE +.\} +.PP +To rename an existing constraint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors RENAME CONSTRAINT zipchk TO zip_check; +.fi +.if n \{\ +.RE +.\} +.PP +To add a not\-null constraint to a column: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ALTER COLUMN street SET NOT NULL; +.fi +.if n \{\ +.RE +.\} +.sp +To remove a not\-null constraint from a column: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ALTER COLUMN street DROP NOT NULL; +.fi +.if n \{\ +.RE +.\} +.PP +To add a check constraint to a table and all its children: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5); +.fi +.if n \{\ +.RE +.\} +.PP +To add a check constraint only to a table and not to its children: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5) NO INHERIT; +.fi +.if n \{\ +.RE +.\} +.sp +(The check constraint will not be inherited by future children, either\&.) +.PP +To remove a check constraint from a table and all its children: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors DROP CONSTRAINT zipchk; +.fi +.if n \{\ +.RE +.\} +.PP +To remove a check constraint from one table only: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE ONLY distributors DROP CONSTRAINT zipchk; +.fi +.if n \{\ +.RE +.\} +.sp +(The check constraint remains in place for any child tables\&.) +.PP +To add a foreign key constraint to a table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address); +.fi +.if n \{\ +.RE +.\} +.PP +To add a foreign key constraint to a table with the least impact on other work: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD CONSTRAINT distfk FOREIGN KEY (address) REFERENCES addresses (address) NOT VALID; +ALTER TABLE distributors VALIDATE CONSTRAINT distfk; +.fi +.if n \{\ +.RE +.\} +.PP +To add a (multicolumn) unique constraint to a table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD CONSTRAINT dist_id_zipcode_key UNIQUE (dist_id, zipcode); +.fi +.if n \{\ +.RE +.\} +.PP +To add an automatically named primary key constraint to a table, noting that a table can only ever have one primary key: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors ADD PRIMARY KEY (dist_id); +.fi +.if n \{\ +.RE +.\} +.PP +To move a table to a different tablespace: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE distributors SET TABLESPACE fasttablespace; +.fi +.if n \{\ +.RE +.\} +.PP +To move a table to a different schema: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE myschema\&.distributors SET SCHEMA yourschema; +.fi +.if n \{\ +.RE +.\} +.PP +To recreate a primary key constraint, without blocking updates while the index is rebuilt: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE UNIQUE INDEX CONCURRENTLY dist_id_temp_idx ON distributors (dist_id); +ALTER TABLE distributors DROP CONSTRAINT distributors_pkey, + ADD CONSTRAINT distributors_pkey PRIMARY KEY USING INDEX dist_id_temp_idx; +.fi +.if n \{\ +.RE +.\} +.PP +To attach a partition to a range\-partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE measurement + ATTACH PARTITION measurement_y2016m07 FOR VALUES FROM (\*(Aq2016\-07\-01\*(Aq) TO (\*(Aq2016\-08\-01\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +To attach a partition to a list\-partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE cities + ATTACH PARTITION cities_ab FOR VALUES IN (\*(Aqa\*(Aq, \*(Aqb\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +To attach a partition to a hash\-partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE orders + ATTACH PARTITION orders_p4 FOR VALUES WITH (MODULUS 4, REMAINDER 3); +.fi +.if n \{\ +.RE +.\} +.PP +To attach a default partition to a partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE cities + ATTACH PARTITION cities_partdef DEFAULT; +.fi +.if n \{\ +.RE +.\} +.PP +To detach a partition from a partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLE measurement + DETACH PARTITION measurement_y2015m12; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The forms +ADD +(without +USING INDEX), +DROP [COLUMN], +DROP IDENTITY, +RESTART, +SET DEFAULT, +SET DATA TYPE +(without +USING), +SET GENERATED, and +SET \fIsequence_option\fR +conform with the SQL standard\&. The other forms are +PostgreSQL +extensions of the SQL standard\&. Also, the ability to specify more than one manipulation in a single +\fBALTER TABLE\fR +command is an extension\&. +.PP +\fBALTER TABLE DROP COLUMN\fR +can be used to drop the only column of a table, leaving a zero\-column table\&. This is an extension of SQL, which disallows zero\-column tables\&. +.SH "SEE ALSO" +CREATE TABLE (\fBCREATE_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TABLESPACE.7 b/doc/src/sgml/man7/ALTER_TABLESPACE.7 new file mode 100644 index 0000000..7cc6fff --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TABLESPACE.7 @@ -0,0 +1,112 @@ +'\" t +.\" Title: ALTER TABLESPACE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TABLESPACE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TABLESPACE \- change the definition of a tablespace +.SH "SYNOPSIS" +.sp +.nf +ALTER TABLESPACE \fIname\fR RENAME TO \fInew_name\fR +ALTER TABLESPACE \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER TABLESPACE \fIname\fR SET ( \fItablespace_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) +ALTER TABLESPACE \fIname\fR RESET ( \fItablespace_option\fR [, \&.\&.\&. ] ) +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TABLESPACE\fR +can be used to change the definition of a tablespace\&. +.PP +You must own the tablespace to change the definition of a tablespace\&. To alter the owner, you must also be a direct or indirect member of the new owning role\&. (Note that superusers have these privileges automatically\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing tablespace\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the tablespace\&. The new name cannot begin with +pg_, as such names are reserved for system tablespaces\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the tablespace\&. +.RE +.PP +\fItablespace_option\fR +.RS 4 +A tablespace parameter to be set or reset\&. Currently, the only available parameters are +\fIseq_page_cost\fR, +\fIrandom_page_cost\fR, +\fIeffective_io_concurrency\fR +and +\fImaintenance_io_concurrency\fR\&. Setting these values for a particular tablespace will override the planner\*(Aqs usual estimate of the cost of reading pages from tables in that tablespace, and the executor\*(Aqs prefetching behavior, as established by the configuration parameters of the same name (see +seq_page_cost, +random_page_cost, +effective_io_concurrency, +maintenance_io_concurrency)\&. This may be useful if one tablespace is located on a disk which is faster or slower than the remainder of the I/O subsystem\&. +.RE +.SH "EXAMPLES" +.PP +Rename tablespace +index_space +to +fast_raid: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLESPACE index_space RENAME TO fast_raid; +.fi +.if n \{\ +.RE +.\} +.PP +Change the owner of tablespace +index_space: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TABLESPACE index_space OWNER TO mary; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER TABLESPACE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE TABLESPACE (\fBCREATE_TABLESPACE\fR(7)), DROP TABLESPACE (\fBDROP_TABLESPACE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TEXT_SEARCH_CONFIGURATION.7 b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_CONFIGURATION.7 new file mode 100644 index 0000000..0a5b189 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_CONFIGURATION.7 @@ -0,0 +1,143 @@ +'\" t +.\" Title: ALTER TEXT SEARCH CONFIGURATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TEXT SEARCH CONFIGURATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TEXT_SEARCH_CONFIGURATION \- change the definition of a text search configuration +.SH "SYNOPSIS" +.sp +.nf +ALTER TEXT SEARCH CONFIGURATION \fIname\fR + ADD MAPPING FOR \fItoken_type\fR [, \&.\&.\&. ] WITH \fIdictionary_name\fR [, \&.\&.\&. ] +ALTER TEXT SEARCH CONFIGURATION \fIname\fR + ALTER MAPPING FOR \fItoken_type\fR [, \&.\&.\&. ] WITH \fIdictionary_name\fR [, \&.\&.\&. ] +ALTER TEXT SEARCH CONFIGURATION \fIname\fR + ALTER MAPPING REPLACE \fIold_dictionary\fR WITH \fInew_dictionary\fR +ALTER TEXT SEARCH CONFIGURATION \fIname\fR + ALTER MAPPING FOR \fItoken_type\fR [, \&.\&.\&. ] REPLACE \fIold_dictionary\fR WITH \fInew_dictionary\fR +ALTER TEXT SEARCH CONFIGURATION \fIname\fR + DROP MAPPING [ IF EXISTS ] FOR \fItoken_type\fR [, \&.\&.\&. ] +ALTER TEXT SEARCH CONFIGURATION \fIname\fR RENAME TO \fInew_name\fR +ALTER TEXT SEARCH CONFIGURATION \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER TEXT SEARCH CONFIGURATION \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TEXT SEARCH CONFIGURATION\fR +changes the definition of a text search configuration\&. You can modify its mappings from token types to dictionaries, or change the configuration\*(Aqs name or owner\&. +.PP +You must be the owner of the configuration to use +\fBALTER TEXT SEARCH CONFIGURATION\fR\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search configuration\&. +.RE +.PP +\fItoken_type\fR +.RS 4 +The name of a token type that is emitted by the configuration\*(Aqs parser\&. +.RE +.PP +\fIdictionary_name\fR +.RS 4 +The name of a text search dictionary to be consulted for the specified token type(s)\&. If multiple dictionaries are listed, they are consulted in the specified order\&. +.RE +.PP +\fIold_dictionary\fR +.RS 4 +The name of a text search dictionary to be replaced in the mapping\&. +.RE +.PP +\fInew_dictionary\fR +.RS 4 +The name of a text search dictionary to be substituted for +\fIold_dictionary\fR\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the text search configuration\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the text search configuration\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the text search configuration\&. +.RE +.PP +The +ADD MAPPING FOR +form installs a list of dictionaries to be consulted for the specified token type(s); it is an error if there is already a mapping for any of the token types\&. The +ALTER MAPPING FOR +form does the same, but first removing any existing mapping for those token types\&. The +ALTER MAPPING REPLACE +forms substitute +\fInew_dictionary\fR +for +\fIold_dictionary\fR +anywhere the latter appears\&. This is done for only the specified token types when +FOR +appears, or for all mappings of the configuration when it doesn\*(Aqt\&. The +DROP MAPPING +form removes all dictionaries for the specified token type(s), causing tokens of those types to be ignored by the text search configuration\&. It is an error if there is no mapping for the token types, unless +IF EXISTS +appears\&. +.SH "EXAMPLES" +.PP +The following example replaces the +english +dictionary with the +swedish +dictionary anywhere that +english +is used within +my_config\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TEXT SEARCH CONFIGURATION my_config + ALTER MAPPING REPLACE english WITH swedish; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER TEXT SEARCH CONFIGURATION\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE TEXT SEARCH CONFIGURATION (\fBCREATE_TEXT_SEARCH_CONFIGURATION\fR(7)), DROP TEXT SEARCH CONFIGURATION (\fBDROP_TEXT_SEARCH_CONFIGURATION\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TEXT_SEARCH_DICTIONARY.7 b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_DICTIONARY.7 new file mode 100644 index 0000000..2183e7f --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_DICTIONARY.7 @@ -0,0 +1,132 @@ +'\" t +.\" Title: ALTER TEXT SEARCH DICTIONARY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TEXT SEARCH DICTIONARY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TEXT_SEARCH_DICTIONARY \- change the definition of a text search dictionary +.SH "SYNOPSIS" +.sp +.nf +ALTER TEXT SEARCH DICTIONARY \fIname\fR ( + \fIoption\fR [ = \fIvalue\fR ] [, \&.\&.\&. ] +) +ALTER TEXT SEARCH DICTIONARY \fIname\fR RENAME TO \fInew_name\fR +ALTER TEXT SEARCH DICTIONARY \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER TEXT SEARCH DICTIONARY \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TEXT SEARCH DICTIONARY\fR +changes the definition of a text search dictionary\&. You can change the dictionary\*(Aqs template\-specific options, or change the dictionary\*(Aqs name or owner\&. +.PP +You must be the owner of the dictionary to use +\fBALTER TEXT SEARCH DICTIONARY\fR\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search dictionary\&. +.RE +.PP +\fIoption\fR +.RS 4 +The name of a template\-specific option to be set for this dictionary\&. +.RE +.PP +\fIvalue\fR +.RS 4 +The new value to use for a template\-specific option\&. If the equal sign and value are omitted, then any previous setting for the option is removed from the dictionary, allowing the default to be used\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the text search dictionary\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The new owner of the text search dictionary\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the text search dictionary\&. +.RE +.PP +Template\-specific options can appear in any order\&. +.SH "EXAMPLES" +.PP +The following example command changes the stopword list for a Snowball\-based dictionary\&. Other parameters remain unchanged\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TEXT SEARCH DICTIONARY my_dict ( StopWords = newrussian ); +.fi +.if n \{\ +.RE +.\} +.PP +The following example command changes the language option to +dutch, and removes the stopword option entirely\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); +.fi +.if n \{\ +.RE +.\} +.PP +The following example command +\(lqupdates\(rq +the dictionary\*(Aqs definition without actually changing anything\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); +.fi +.if n \{\ +.RE +.\} +.sp +(The reason this works is that the option removal code doesn\*(Aqt complain if there is no such option\&.) This trick is useful when changing configuration files for the dictionary: the +\fBALTER\fR +will force existing database sessions to re\-read the configuration files, which otherwise they would never do if they had read them earlier\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER TEXT SEARCH DICTIONARY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE TEXT SEARCH DICTIONARY (\fBCREATE_TEXT_SEARCH_DICTIONARY\fR(7)), DROP TEXT SEARCH DICTIONARY (\fBDROP_TEXT_SEARCH_DICTIONARY\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TEXT_SEARCH_PARSER.7 b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_PARSER.7 new file mode 100644 index 0000000..b1b365a --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_PARSER.7 @@ -0,0 +1,67 @@ +'\" t +.\" Title: ALTER TEXT SEARCH PARSER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TEXT SEARCH PARSER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TEXT_SEARCH_PARSER \- change the definition of a text search parser +.SH "SYNOPSIS" +.sp +.nf +ALTER TEXT SEARCH PARSER \fIname\fR RENAME TO \fInew_name\fR +ALTER TEXT SEARCH PARSER \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TEXT SEARCH PARSER\fR +changes the definition of a text search parser\&. Currently, the only supported functionality is to change the parser\*(Aqs name\&. +.PP +You must be a superuser to use +\fBALTER TEXT SEARCH PARSER\fR\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search parser\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the text search parser\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the text search parser\&. +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER TEXT SEARCH PARSER\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE TEXT SEARCH PARSER (\fBCREATE_TEXT_SEARCH_PARSER\fR(7)), DROP TEXT SEARCH PARSER (\fBDROP_TEXT_SEARCH_PARSER\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TEXT_SEARCH_TEMPLATE.7 b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_TEMPLATE.7 new file mode 100644 index 0000000..819cafc --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TEXT_SEARCH_TEMPLATE.7 @@ -0,0 +1,67 @@ +'\" t +.\" Title: ALTER TEXT SEARCH TEMPLATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TEXT SEARCH TEMPLATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TEXT_SEARCH_TEMPLATE \- change the definition of a text search template +.SH "SYNOPSIS" +.sp +.nf +ALTER TEXT SEARCH TEMPLATE \fIname\fR RENAME TO \fInew_name\fR +ALTER TEXT SEARCH TEMPLATE \fIname\fR SET SCHEMA \fInew_schema\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TEXT SEARCH TEMPLATE\fR +changes the definition of a text search template\&. Currently, the only supported functionality is to change the template\*(Aqs name\&. +.PP +You must be a superuser to use +\fBALTER TEXT SEARCH TEMPLATE\fR\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search template\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name of the text search template\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the text search template\&. +.RE +.SH "COMPATIBILITY" +.PP +There is no +\fBALTER TEXT SEARCH TEMPLATE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE TEXT SEARCH TEMPLATE (\fBCREATE_TEXT_SEARCH_TEMPLATE\fR(7)), DROP TEXT SEARCH TEMPLATE (\fBDROP_TEXT_SEARCH_TEMPLATE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TRIGGER.7 b/doc/src/sgml/man7/ALTER_TRIGGER.7 new file mode 100644 index 0000000..1e9840d --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TRIGGER.7 @@ -0,0 +1,114 @@ +'\" t +.\" Title: ALTER TRIGGER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TRIGGER \- change the definition of a trigger +.SH "SYNOPSIS" +.sp +.nf +ALTER TRIGGER \fIname\fR ON \fItable_name\fR RENAME TO \fInew_name\fR +ALTER TRIGGER \fIname\fR ON \fItable_name\fR [ NO ] DEPENDS ON EXTENSION \fIextension_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TRIGGER\fR +changes properties of an existing trigger\&. +.PP +The +RENAME +clause changes the name of the given trigger without otherwise changing the trigger definition\&. If the table that the trigger is on is a partitioned table, then corresponding clone triggers in the partitions are renamed too\&. +.PP +The +DEPENDS ON EXTENSION +clause marks the trigger as dependent on an extension, such that if the extension is dropped, the trigger will automatically be dropped as well\&. +.PP +You must own the table on which the trigger acts to be allowed to change its properties\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an existing trigger to alter\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name of the table on which this trigger acts\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the trigger\&. +.RE +.PP +\fIextension_name\fR +.RS 4 +The name of the extension that the trigger is to depend on (or no longer dependent on, if +NO +is specified)\&. A trigger that\*(Aqs marked as dependent on an extension is automatically dropped when the extension is dropped\&. +.RE +.SH "NOTES" +.PP +The ability to temporarily enable or disable a trigger is provided by +\fBALTER TABLE\fR, not by +\fBALTER TRIGGER\fR, because +\fBALTER TRIGGER\fR +has no convenient way to express the option of enabling or disabling all of a table\*(Aqs triggers at once\&. +.SH "EXAMPLES" +.PP +To rename an existing trigger: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TRIGGER emp_stamp ON emp RENAME TO emp_track_chgs; +.fi +.if n \{\ +.RE +.\} +.PP +To mark a trigger as being dependent on an extension: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TRIGGER emp_stamp ON emp DEPENDS ON EXTENSION emplib; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER TRIGGER\fR +is a +PostgreSQL +extension of the SQL standard\&. +.SH "SEE ALSO" +ALTER TABLE (\fBALTER_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_TYPE.7 b/doc/src/sgml/man7/ALTER_TYPE.7 new file mode 100644 index 0000000..58becdb --- /dev/null +++ b/doc/src/sgml/man7/ALTER_TYPE.7 @@ -0,0 +1,424 @@ +'\" t +.\" Title: ALTER TYPE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER TYPE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_TYPE \- change the definition of a type +.SH "SYNOPSIS" +.sp +.nf +ALTER TYPE \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER TYPE \fIname\fR RENAME TO \fInew_name\fR +ALTER TYPE \fIname\fR SET SCHEMA \fInew_schema\fR +ALTER TYPE \fIname\fR RENAME ATTRIBUTE \fIattribute_name\fR TO \fInew_attribute_name\fR [ CASCADE | RESTRICT ] +ALTER TYPE \fIname\fR \fIaction\fR [, \&.\&.\&. ] +ALTER TYPE \fIname\fR ADD VALUE [ IF NOT EXISTS ] \fInew_enum_value\fR [ { BEFORE | AFTER } \fIneighbor_enum_value\fR ] +ALTER TYPE \fIname\fR RENAME VALUE \fIexisting_enum_value\fR TO \fInew_enum_value\fR +ALTER TYPE \fIname\fR SET ( \fIproperty\fR = \fIvalue\fR [, \&.\&.\&. ] ) + +where \fIaction\fR is one of: + + ADD ATTRIBUTE \fIattribute_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ CASCADE | RESTRICT ] + DROP ATTRIBUTE [ IF EXISTS ] \fIattribute_name\fR [ CASCADE | RESTRICT ] + ALTER ATTRIBUTE \fIattribute_name\fR [ SET DATA ] TYPE \fIdata_type\fR [ COLLATE \fIcollation\fR ] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBALTER TYPE\fR +changes the definition of an existing type\&. There are several subforms: +.PP +OWNER +.RS 4 +This form changes the owner of the type\&. +.RE +.PP +RENAME +.RS 4 +This form changes the name of the type\&. +.RE +.PP +SET SCHEMA +.RS 4 +This form moves the type into another schema\&. +.RE +.PP +RENAME ATTRIBUTE +.RS 4 +This form is only usable with composite types\&. It changes the name of an individual attribute of the type\&. +.RE +.PP +ADD ATTRIBUTE +.RS 4 +This form adds a new attribute to a composite type, using the same syntax as +\fBCREATE TYPE\fR\&. +.RE +.PP +DROP ATTRIBUTE [ IF EXISTS ] +.RS 4 +This form drops an attribute from a composite type\&. If +IF EXISTS +is specified and the attribute does not exist, no error is thrown\&. In this case a notice is issued instead\&. +.RE +.PP +ALTER ATTRIBUTE \&.\&.\&. SET DATA TYPE +.RS 4 +This form changes the type of an attribute of a composite type\&. +.RE +.PP +ADD VALUE [ IF NOT EXISTS ] [ BEFORE | AFTER ] +.RS 4 +This form adds a new value to an enum type\&. The new value\*(Aqs place in the enum\*(Aqs ordering can be specified as being +BEFORE +or +AFTER +one of the existing values\&. Otherwise, the new item is added at the end of the list of values\&. +.sp +If +IF NOT EXISTS +is specified, it is not an error if the type already contains the new value: a notice is issued but no other action is taken\&. Otherwise, an error will occur if the new value is already present\&. +.RE +.PP +RENAME VALUE +.RS 4 +This form renames a value of an enum type\&. The value\*(Aqs place in the enum\*(Aqs ordering is not affected\&. An error will occur if the specified value is not present or the new name is already present\&. +.RE +.PP +SET ( \fIproperty\fR = \fIvalue\fR [, \&.\&.\&. ] ) +.RS 4 +This form is only applicable to base types\&. It allows adjustment of a subset of the base\-type properties that can be set in +\fBCREATE TYPE\fR\&. Specifically, these properties can be changed: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +RECEIVE +can be set to the name of a binary input function, or +NONE +to remove the type\*(Aqs binary input function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SEND +can be set to the name of a binary output function, or +NONE +to remove the type\*(Aqs binary output function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TYPMOD_IN +can be set to the name of a type modifier input function, or +NONE +to remove the type\*(Aqs type modifier input function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +TYPMOD_OUT +can be set to the name of a type modifier output function, or +NONE +to remove the type\*(Aqs type modifier output function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +ANALYZE +can be set to the name of a type\-specific statistics collection function, or +NONE +to remove the type\*(Aqs statistics collection function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +SUBSCRIPT +can be set to the name of a type\-specific subscripting handler function, or +NONE +to remove the type\*(Aqs subscripting handler function\&. Using this option requires superuser privilege\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +STORAGE +can be set to +plain, +extended, +external, or +main +(see +Section\ \&73.2 +for more information about what these mean)\&. However, changing from +plain +to another setting requires superuser privilege (because it requires that the type\*(Aqs C functions all be TOAST\-ready), and changing to +plain +from another setting is not allowed at all (since the type may already have TOASTed values present in the database)\&. Note that changing this option doesn\*(Aqt by itself change any stored data, it just sets the default TOAST strategy to be used for table columns created in the future\&. See +ALTER TABLE (\fBALTER_TABLE\fR(7)) +to change the TOAST strategy for existing table columns\&. +.RE +.sp +See +CREATE TYPE (\fBCREATE_TYPE\fR(7)) +for more details about these type properties\&. Note that where appropriate, a change in these properties for a base type will be propagated automatically to domains based on that type\&. +.RE +.PP +The +ADD ATTRIBUTE, +DROP ATTRIBUTE, and +ALTER ATTRIBUTE +actions can be combined into a list of multiple alterations to apply in parallel\&. For example, it is possible to add several attributes and/or alter the type of several attributes in a single command\&. +.PP +You must own the type to use +\fBALTER TYPE\fR\&. To change the schema of a type, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the type\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the type\&. However, a superuser can alter ownership of any type anyway\&.) To add an attribute or alter an attribute type, you must also have +USAGE +privilege on the attribute\*(Aqs data type\&. +.SH "PARAMETERS" +.PP +.PP +\fIname\fR +.RS 4 +The name (possibly schema\-qualified) of an existing type to alter\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the type\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the type\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the type\&. +.RE +.PP +\fIattribute_name\fR +.RS 4 +The name of the attribute to add, alter, or drop\&. +.RE +.PP +\fInew_attribute_name\fR +.RS 4 +The new name of the attribute to be renamed\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The data type of the attribute to add, or the new type of the attribute to alter\&. +.RE +.PP +\fInew_enum_value\fR +.RS 4 +The new value to be added to an enum type\*(Aqs list of values, or the new name to be given to an existing value\&. Like all enum literals, it needs to be quoted\&. +.RE +.PP +\fIneighbor_enum_value\fR +.RS 4 +The existing enum value that the new value should be added immediately before or after in the enum type\*(Aqs sort ordering\&. Like all enum literals, it needs to be quoted\&. +.RE +.PP +\fIexisting_enum_value\fR +.RS 4 +The existing enum value that should be renamed\&. Like all enum literals, it needs to be quoted\&. +.RE +.PP +\fIproperty\fR +.RS 4 +The name of a base\-type property to be modified; see above for possible values\&. +.RE +.PP +CASCADE +.RS 4 +Automatically propagate the operation to typed tables of the type being altered, and their descendants\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse the operation if the type being altered is the type of a typed table\&. This is the default\&. +.RE +.SH "NOTES" +.PP +If +\fBALTER TYPE \&.\&.\&. ADD VALUE\fR +(the form that adds a new value to an enum type) is executed inside a transaction block, the new value cannot be used until after the transaction has been committed\&. +.PP +Comparisons involving an added enum value will sometimes be slower than comparisons involving only original members of the enum type\&. This will usually only occur if +BEFORE +or +AFTER +is used to set the new value\*(Aqs sort position somewhere other than at the end of the list\&. However, sometimes it will happen even though the new value is added at the end (this occurs if the OID counter +\(lqwrapped around\(rq +since the original creation of the enum type)\&. The slowdown is usually insignificant; but if it matters, optimal performance can be regained by dropping and recreating the enum type, or by dumping and restoring the database\&. +.SH "EXAMPLES" +.PP +To rename a data type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE electronic_mail RENAME TO email; +.fi +.if n \{\ +.RE +.\} +.PP +To change the owner of the type +email +to +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE email OWNER TO joe; +.fi +.if n \{\ +.RE +.\} +.PP +To change the schema of the type +email +to +customers: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE email SET SCHEMA customers; +.fi +.if n \{\ +.RE +.\} +.PP +To add a new attribute to a composite type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE compfoo ADD ATTRIBUTE f3 int; +.fi +.if n \{\ +.RE +.\} +.PP +To add a new value to an enum type in a particular sort position: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE colors ADD VALUE \*(Aqorange\*(Aq AFTER \*(Aqred\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To rename an enum value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER TYPE colors RENAME VALUE \*(Aqpurple\*(Aq TO \*(Aqmauve\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To create binary I/O functions for an existing base type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION mytypesend(mytype) RETURNS bytea \&.\&.\&.; +CREATE FUNCTION mytyperecv(internal, oid, integer) RETURNS mytype \&.\&.\&.; +ALTER TYPE mytype SET ( + SEND = mytypesend, + RECEIVE = mytyperecv +); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The variants to add and drop attributes are part of the SQL standard; the other variants are PostgreSQL extensions\&. +.SH "SEE ALSO" +CREATE TYPE (\fBCREATE_TYPE\fR(7)), DROP TYPE (\fBDROP_TYPE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_USER.7 b/doc/src/sgml/man7/ALTER_USER.7 new file mode 100644 index 0000000..c2b6f04 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_USER.7 @@ -0,0 +1,77 @@ +'\" t +.\" Title: ALTER USER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER USER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_USER \- change a database role +.SH "SYNOPSIS" +.sp +.nf +ALTER USER \fIrole_specification\fR [ WITH ] \fIoption\fR [ \&.\&.\&. ] + +where \fIoption\fR can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | REPLICATION | NOREPLICATION + | BYPASSRLS | NOBYPASSRLS + | CONNECTION LIMIT \fIconnlimit\fR + | [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq | PASSWORD NULL + | VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq + +ALTER USER \fIname\fR RENAME TO \fInew_name\fR + +ALTER USER { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] SET \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | DEFAULT } +ALTER USER { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] SET \fIconfiguration_parameter\fR FROM CURRENT +ALTER USER { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] RESET \fIconfiguration_parameter\fR +ALTER USER { \fIrole_specification\fR | ALL } [ IN DATABASE \fIdatabase_name\fR ] RESET ALL + +where \fIrole_specification\fR can be: + + \fIrole_name\fR + | CURRENT_ROLE + | CURRENT_USER + | SESSION_USER +.fi +.SH "DESCRIPTION" +.PP +\fBALTER USER\fR +is now an alias for +\fBALTER ROLE\fR\&. +.SH "COMPATIBILITY" +.PP +The +\fBALTER USER\fR +statement is a +PostgreSQL +extension\&. The SQL standard leaves the definition of users to the implementation\&. +.SH "SEE ALSO" +ALTER ROLE (\fBALTER_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_USER_MAPPING.7 b/doc/src/sgml/man7/ALTER_USER_MAPPING.7 new file mode 100644 index 0000000..9b13af8 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_USER_MAPPING.7 @@ -0,0 +1,104 @@ +'\" t +.\" Title: ALTER USER MAPPING +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER USER MAPPING" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_USER_MAPPING \- change the definition of a user mapping +.SH "SYNOPSIS" +.sp +.nf +ALTER USER MAPPING FOR { \fIuser_name\fR | USER | CURRENT_ROLE | CURRENT_USER | SESSION_USER | PUBLIC } + SERVER \fIserver_name\fR + OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] ) +.fi +.SH "DESCRIPTION" +.PP +\fBALTER USER MAPPING\fR +changes the definition of a user mapping\&. +.PP +The owner of a foreign server can alter user mappings for that server for any user\&. Also, a user can alter a user mapping for their own user name if +USAGE +privilege on the server has been granted to the user\&. +.SH "PARAMETERS" +.PP +\fIuser_name\fR +.RS 4 +User name of the mapping\&. +CURRENT_ROLE, +CURRENT_USER, and +USER +match the name of the current user\&. +PUBLIC +is used to match all present and future user names in the system\&. +.RE +.PP +\fIserver_name\fR +.RS 4 +Server name of the user mapping\&. +.RE +.PP +OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] ) +.RS 4 +Change options for the user mapping\&. The new options override any previously specified options\&. +ADD, +SET, and +DROP +specify the action to be performed\&. +ADD +is assumed if no operation is explicitly specified\&. Option names must be unique; options are also validated by the server\*(Aqs foreign\-data wrapper\&. +.RE +.SH "EXAMPLES" +.PP +Change the password for user mapping +bob, server +foo: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER USER MAPPING FOR bob SERVER foo OPTIONS (SET password \*(Aqpublic\*(Aq); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER USER MAPPING\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. There is a subtle syntax issue: The standard omits the +FOR +key word\&. Since both +CREATE USER MAPPING +and +DROP USER MAPPING +use +FOR +in analogous positions, and IBM DB2 (being the other major SQL/MED implementation) also requires it for +ALTER USER MAPPING, PostgreSQL diverges from the standard here in the interest of consistency and interoperability\&. +.SH "SEE ALSO" +CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7)), DROP USER MAPPING (\fBDROP_USER_MAPPING\fR(7)) diff --git a/doc/src/sgml/man7/ALTER_VIEW.7 b/doc/src/sgml/man7/ALTER_VIEW.7 new file mode 100644 index 0000000..a5d58c1 --- /dev/null +++ b/doc/src/sgml/man7/ALTER_VIEW.7 @@ -0,0 +1,178 @@ +'\" t +.\" Title: ALTER VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ALTER VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ALTER_VIEW \- change the definition of a view +.SH "SYNOPSIS" +.sp +.nf +ALTER VIEW [ IF EXISTS ] \fIname\fR ALTER [ COLUMN ] \fIcolumn_name\fR SET DEFAULT \fIexpression\fR +ALTER VIEW [ IF EXISTS ] \fIname\fR ALTER [ COLUMN ] \fIcolumn_name\fR DROP DEFAULT +ALTER VIEW [ IF EXISTS ] \fIname\fR OWNER TO { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +ALTER VIEW [ IF EXISTS ] \fIname\fR RENAME [ COLUMN ] \fIcolumn_name\fR TO \fInew_column_name\fR +ALTER VIEW [ IF EXISTS ] \fIname\fR RENAME TO \fInew_name\fR +ALTER VIEW [ IF EXISTS ] \fIname\fR SET SCHEMA \fInew_schema\fR +ALTER VIEW [ IF EXISTS ] \fIname\fR SET ( \fIview_option_name\fR [= \fIview_option_value\fR] [, \&.\&.\&. ] ) +ALTER VIEW [ IF EXISTS ] \fIname\fR RESET ( \fIview_option_name\fR [, \&.\&.\&. ] ) +.fi +.SH "DESCRIPTION" +.PP +\fBALTER VIEW\fR +changes various auxiliary properties of a view\&. (If you want to modify the view\*(Aqs defining query, use +\fBCREATE OR REPLACE VIEW\fR\&.) +.PP +You must own the view to use +\fBALTER VIEW\fR\&. To change a view\*(Aqs schema, you must also have +CREATE +privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have +CREATE +privilege on the view\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the view\&. However, a superuser can alter ownership of any view anyway\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing view\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +Name of an existing column\&. +.RE +.PP +\fInew_column_name\fR +.RS 4 +New name for an existing column\&. +.RE +.PP +IF EXISTS +.RS 4 +Do not throw an error if the view does not exist\&. A notice is issued in this case\&. +.RE +.PP +SET/DROP DEFAULT +.RS 4 +These forms set or remove the default value for a column\&. A view column\*(Aqs default value is substituted into any +\fBINSERT\fR +or +\fBUPDATE\fR +command whose target is the view, before applying any rules or triggers for the view\&. The view\*(Aqs default will therefore take precedence over any default values from underlying relations\&. +.RE +.PP +\fInew_owner\fR +.RS 4 +The user name of the new owner of the view\&. +.RE +.PP +\fInew_name\fR +.RS 4 +The new name for the view\&. +.RE +.PP +\fInew_schema\fR +.RS 4 +The new schema for the view\&. +.RE +.PP +SET ( \fIview_option_name\fR [= \fIview_option_value\fR] [, \&.\&.\&. ] ) +.br +RESET ( \fIview_option_name\fR [, \&.\&.\&. ] ) +.RS 4 +Sets or resets a view option\&. Currently supported options are: +.PP +check_option (enum) +.RS 4 +Changes the check option of the view\&. The value must be +local +or +cascaded\&. +.RE +.PP +security_barrier (boolean) +.RS 4 +Changes the security\-barrier property of the view\&. The value must be a Boolean value, such as +true +or +false\&. +.RE +.PP +security_invoker (boolean) +.RS 4 +Changes the security\-invoker property of the view\&. The value must be a Boolean value, such as +true +or +false\&. +.RE +.RE +.SH "NOTES" +.PP +For historical reasons, +\fBALTER TABLE\fR +can be used with views too; but the only variants of +\fBALTER TABLE\fR +that are allowed with views are equivalent to the ones shown above\&. +.SH "EXAMPLES" +.PP +To rename the view +foo +to +bar: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ALTER VIEW foo RENAME TO bar; +.fi +.if n \{\ +.RE +.\} +.PP +To attach a default column value to an updatable view: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE base_table (id int, ts timestamptz); +CREATE VIEW a_view AS SELECT * FROM base_table; +ALTER VIEW a_view ALTER COLUMN ts SET DEFAULT now(); +INSERT INTO base_table(id) VALUES(1); \-\- ts will receive a NULL +INSERT INTO a_view(id) VALUES(2); \-\- ts will receive the current time +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBALTER VIEW\fR +is a +PostgreSQL +extension of the SQL standard\&. +.SH "SEE ALSO" +CREATE VIEW (\fBCREATE_VIEW\fR(7)), DROP VIEW (\fBDROP_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/ANALYZE.7 b/doc/src/sgml/man7/ANALYZE.7 new file mode 100644 index 0000000..f920228 --- /dev/null +++ b/doc/src/sgml/man7/ANALYZE.7 @@ -0,0 +1,215 @@ +'\" t +.\" Title: ANALYZE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ANALYZE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ANALYZE \- collect statistics about a database +.SH "SYNOPSIS" +.sp +.nf +ANALYZE [ ( \fIoption\fR [, \&.\&.\&.] ) ] [ \fItable_and_columns\fR [, \&.\&.\&.] ] +ANALYZE [ VERBOSE ] [ \fItable_and_columns\fR [, \&.\&.\&.] ] + +where \fIoption\fR can be one of: + + VERBOSE [ \fIboolean\fR ] + SKIP_LOCKED [ \fIboolean\fR ] + +and \fItable_and_columns\fR is: + + \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBANALYZE\fR +collects statistics about the contents of tables in the database, and stores the results in the +pg_statistic +system catalog\&. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries\&. +.PP +Without a +\fItable_and_columns\fR +list, +\fBANALYZE\fR +processes every table and materialized view in the current database that the current user has permission to analyze\&. With a list, +\fBANALYZE\fR +processes only those table(s)\&. It is further possible to give a list of column names for a table, in which case only the statistics for those columns are collected\&. +.PP +When the option list is surrounded by parentheses, the options can be written in any order\&. The parenthesized syntax was added in +PostgreSQL +11; the unparenthesized syntax is deprecated\&. +.SH "PARAMETERS" +.PP +VERBOSE +.RS 4 +Enables display of progress messages\&. +.RE +.PP +SKIP_LOCKED +.RS 4 +Specifies that +\fBANALYZE\fR +should not wait for any conflicting locks to be released when beginning work on a relation: if a relation cannot be locked immediately without waiting, the relation is skipped\&. Note that even with this option, +\fBANALYZE\fR +may still block when opening the relation\*(Aqs indexes or when acquiring sample rows from partitions, table inheritance children, and some types of foreign tables\&. Also, while +\fBANALYZE\fR +ordinarily processes all partitions of specified partitioned tables, this option will cause +\fBANALYZE\fR +to skip all partitions if there is a conflicting lock on the partitioned table\&. +.RE +.PP +\fIboolean\fR +.RS 4 +Specifies whether the selected option should be turned on or off\&. You can write +TRUE, +ON, or +1 +to enable the option, and +FALSE, +OFF, or +0 +to disable it\&. The +\fIboolean\fR +value can also be omitted, in which case +TRUE +is assumed\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (possibly schema\-qualified) of a specific table to analyze\&. If omitted, all regular tables, partitioned tables, and materialized views in the current database are analyzed (but not foreign tables)\&. If the specified table is a partitioned table, both the inheritance statistics of the partitioned table as a whole and statistics of the individual partitions are updated\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a specific column to analyze\&. Defaults to all columns\&. +.RE +.SH "OUTPUTS" +.PP +When +VERBOSE +is specified, +\fBANALYZE\fR +emits progress messages to indicate which table is currently being processed\&. Various statistics about the tables are printed as well\&. +.SH "NOTES" +.PP +To analyze a table, one must ordinarily be the table\*(Aqs owner or a superuser\&. However, database owners are allowed to analyze all tables in their databases, except shared catalogs\&. (The restriction for shared catalogs means that a true database\-wide +\fBANALYZE\fR +can only be performed by a superuser\&.) +\fBANALYZE\fR +will skip over any tables that the calling user does not have permission to analyze\&. +.PP +Foreign tables are analyzed only when explicitly selected\&. Not all foreign data wrappers support +\fBANALYZE\fR\&. If the table\*(Aqs wrapper does not support +\fBANALYZE\fR, the command prints a warning and does nothing\&. +.PP +In the default +PostgreSQL +configuration, the autovacuum daemon (see +Section\ \&25.1.6) takes care of automatic analyzing of tables when they are first loaded with data, and as they change throughout regular operation\&. When autovacuum is disabled, it is a good idea to run +\fBANALYZE\fR +periodically, or just after making major changes in the contents of a table\&. Accurate statistics will help the planner to choose the most appropriate query plan, and thereby improve the speed of query processing\&. A common strategy for read\-mostly databases is to run +\fBVACUUM\fR +and +\fBANALYZE\fR +once a day during a low\-usage time of day\&. (This will not be sufficient if there is heavy update activity\&.) +.PP +\fBANALYZE\fR +requires only a read lock on the target table, so it can run in parallel with other activity on the table\&. +.PP +The statistics collected by +\fBANALYZE\fR +usually include a list of some of the most common values in each column and a histogram showing the approximate data distribution in each column\&. One or both of these can be omitted if +\fBANALYZE\fR +deems them uninteresting (for example, in a unique\-key column, there are no common values) or if the column data type does not support the appropriate operators\&. There is more information about the statistics in +Chapter\ \&25\&. +.PP +For large tables, +\fBANALYZE\fR +takes a random sample of the table contents, rather than examining every row\&. This allows even very large tables to be analyzed in a small amount of time\&. Note, however, that the statistics are only approximate, and will change slightly each time +\fBANALYZE\fR +is run, even if the actual table contents did not change\&. This might result in small changes in the planner\*(Aqs estimated costs shown by +\fBEXPLAIN\fR\&. In rare situations, this non\-determinism will cause the planner\*(Aqs choices of query plans to change after +\fBANALYZE\fR +is run\&. To avoid this, raise the amount of statistics collected by +\fBANALYZE\fR, as described below\&. +.PP +The extent of analysis can be controlled by adjusting the +default_statistics_target +configuration variable, or on a column\-by\-column basis by setting the per\-column statistics target with +\fBALTER TABLE \&.\&.\&. ALTER COLUMN \&.\&.\&. SET STATISTICS\fR\&. The target value sets the maximum number of entries in the most\-common\-value list and the maximum number of bins in the histogram\&. The default target value is 100, but this can be adjusted up or down to trade off accuracy of planner estimates against the time taken for +\fBANALYZE\fR +and the amount of space occupied in +pg_statistic\&. In particular, setting the statistics target to zero disables collection of statistics for that column\&. It might be useful to do that for columns that are never used as part of the +WHERE, +GROUP BY, or +ORDER BY +clauses of queries, since the planner will have no use for statistics on such columns\&. +.PP +The largest statistics target among the columns being analyzed determines the number of table rows sampled to prepare the statistics\&. Increasing the target causes a proportional increase in the time and space needed to do +\fBANALYZE\fR\&. +.PP +One of the values estimated by +\fBANALYZE\fR +is the number of distinct values that appear in each column\&. Because only a subset of the rows are examined, this estimate can sometimes be quite inaccurate, even with the largest possible statistics target\&. If this inaccuracy leads to bad query plans, a more accurate value can be determined manually and then installed with +\fBALTER TABLE \&.\&.\&. ALTER COLUMN \&.\&.\&. SET (n_distinct = \&.\&.\&.)\fR\&. +.PP +If the table being analyzed has inheritance children, +\fBANALYZE\fR +gathers two sets of statistics: one on the rows of the parent table only, and a second including rows of both the parent table and all of its children\&. This second set of statistics is needed when planning queries that process the inheritance tree as a whole\&. The child tables themselves are not individually analyzed in this case\&. The autovacuum daemon, however, will only consider inserts or updates on the parent table itself when deciding whether to trigger an automatic analyze for that table\&. If that table is rarely inserted into or updated, the inheritance statistics will not be up to date unless you run +\fBANALYZE\fR +manually\&. +.PP +For partitioned tables, +\fBANALYZE\fR +gathers statistics by sampling rows from all partitions; in addition, it will recurse into each partition and update its statistics\&. Each leaf partition is analyzed only once, even with multi\-level partitioning\&. No statistics are collected for only the parent table (without data from its partitions), because with partitioning it\*(Aqs guaranteed to be empty\&. +.PP +The autovacuum daemon does not process partitioned tables, nor does it process inheritance parents if only the children are ever modified\&. It is usually necessary to periodically run a manual +\fBANALYZE\fR +to keep the statistics of the table hierarchy up to date\&. +.PP +If any child tables or partitions are foreign tables whose foreign data wrappers do not support +\fBANALYZE\fR, those tables are ignored while gathering inheritance statistics\&. +.PP +If the table being analyzed is completely empty, +\fBANALYZE\fR +will not record new statistics for that table\&. Any existing statistics will be retained\&. +.PP +Each backend running +\fBANALYZE\fR +will report its progress in the +pg_stat_progress_analyze +view\&. See +Section\ \&28.4.1 +for details\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBANALYZE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBVACUUM\fR(7), \fBvacuumdb\fR(1), Section\ \&20.4.4, Section\ \&25.1.6, Section\ \&28.4.1 diff --git a/doc/src/sgml/man7/BEGIN.7 b/doc/src/sgml/man7/BEGIN.7 new file mode 100644 index 0000000..2260340 --- /dev/null +++ b/doc/src/sgml/man7/BEGIN.7 @@ -0,0 +1,128 @@ +'\" t +.\" Title: BEGIN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "BEGIN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +BEGIN \- start a transaction block +.SH "SYNOPSIS" +.sp +.nf +BEGIN [ WORK | TRANSACTION ] [ \fItransaction_mode\fR [, \&.\&.\&.] ] + +where \fItransaction_mode\fR is one of: + + ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } + READ WRITE | READ ONLY + [ NOT ] DEFERRABLE +.fi +.SH "DESCRIPTION" +.PP +\fBBEGIN\fR +initiates a transaction block, that is, all statements after a +\fBBEGIN\fR +command will be executed in a single transaction until an explicit +\fBCOMMIT\fR +or +\fBROLLBACK\fR +is given\&. By default (without +\fBBEGIN\fR), +PostgreSQL +executes transactions in +\(lqautocommit\(rq +mode, that is, each statement is executed in its own transaction and a commit is implicitly performed at the end of the statement (if execution was successful, otherwise a rollback is done)\&. +.PP +Statements are executed more quickly in a transaction block, because transaction start/commit requires significant CPU and disk activity\&. Execution of multiple statements inside a transaction is also useful to ensure consistency when making several related changes: other sessions will be unable to see the intermediate states wherein not all the related updates have been done\&. +.PP +If the isolation level, read/write mode, or deferrable mode is specified, the new transaction has those characteristics, as if +\fBSET TRANSACTION\fR +was executed\&. +.SH "PARAMETERS" +.PP +WORK +.br +TRANSACTION +.RS 4 +Optional key words\&. They have no effect\&. +.RE +.PP +Refer to +SET TRANSACTION (\fBSET_TRANSACTION\fR(7)) +for information on the meaning of the other parameters to this statement\&. +.SH "NOTES" +.PP +\fBSTART TRANSACTION\fR +has the same functionality as +\fBBEGIN\fR\&. +.PP +Use +\fBCOMMIT\fR +or +\fBROLLBACK\fR +to terminate a transaction block\&. +.PP +Issuing +\fBBEGIN\fR +when already inside a transaction block will provoke a warning message\&. The state of the transaction is not affected\&. To nest transactions within a transaction block, use savepoints (see +\fBSAVEPOINT\fR(7))\&. +.PP +For reasons of backwards compatibility, the commas between successive +\fItransaction_modes\fR +can be omitted\&. +.SH "EXAMPLES" +.PP +To begin a transaction block: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBBEGIN\fR +is a +PostgreSQL +language extension\&. It is equivalent to the SQL\-standard command +\fBSTART TRANSACTION\fR, whose reference page contains additional compatibility information\&. +.PP +The +DEFERRABLE +\fItransaction_mode\fR +is a +PostgreSQL +language extension\&. +.PP +Incidentally, the +BEGIN +key word is used for a different purpose in embedded SQL\&. You are advised to be careful about the transaction semantics when porting database applications\&. +.SH "SEE ALSO" +\fBCOMMIT\fR(7), \fBROLLBACK\fR(7), START TRANSACTION (\fBSTART_TRANSACTION\fR(7)), \fBSAVEPOINT\fR(7) diff --git a/doc/src/sgml/man7/CALL.7 b/doc/src/sgml/man7/CALL.7 new file mode 100644 index 0000000..63758cb --- /dev/null +++ b/doc/src/sgml/man7/CALL.7 @@ -0,0 +1,108 @@ +'\" t +.\" Title: CALL +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CALL" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CALL \- invoke a procedure +.SH "SYNOPSIS" +.sp +.nf +CALL \fIname\fR ( [ \fIargument\fR ] [, \&.\&.\&.] ) +.fi +.SH "DESCRIPTION" +.PP +\fBCALL\fR +executes a procedure\&. +.PP +If the procedure has any output parameters, then a result row will be returned, containing the values of those parameters\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the procedure\&. +.RE +.PP +\fIargument\fR +.RS 4 +An argument expression for the procedure call\&. +.sp +Arguments can include parameter names, using the syntax +\fIname\fR => \fIvalue\fR\&. This works the same as in ordinary function calls; see +Section\ \&4.3 +for details\&. +.sp +Arguments must be supplied for all procedure parameters that lack defaults, including +OUT +parameters\&. However, arguments matching +OUT +parameters are not evaluated, so it\*(Aqs customary to just write +NULL +for them\&. (Writing something else for an +OUT +parameter might cause compatibility problems with future +PostgreSQL +versions\&.) +.RE +.SH "NOTES" +.PP +The user must have +EXECUTE +privilege on the procedure in order to be allowed to invoke it\&. +.PP +To call a function (not a procedure), use +\fBSELECT\fR +instead\&. +.PP +If +\fBCALL\fR +is executed in a transaction block, then the called procedure cannot execute transaction control statements\&. Transaction control statements are only allowed if +\fBCALL\fR +is executed in its own transaction\&. +.PP +PL/pgSQL +handles output parameters in +\fBCALL\fR +commands differently; see +Section\ \&43.6.3\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +CALL do_db_maintenance(); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCALL\fR +conforms to the SQL standard, except for the handling of output parameters\&. The standard says that users should write variables to receive the values of output parameters\&. +.SH "SEE ALSO" +CREATE PROCEDURE (\fBCREATE_PROCEDURE\fR(7)) diff --git a/doc/src/sgml/man7/CHECKPOINT.7 b/doc/src/sgml/man7/CHECKPOINT.7 new file mode 100644 index 0000000..5065896 --- /dev/null +++ b/doc/src/sgml/man7/CHECKPOINT.7 @@ -0,0 +1,65 @@ +'\" t +.\" Title: CHECKPOINT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CHECKPOINT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CHECKPOINT \- force a write\-ahead log checkpoint +.SH "SYNOPSIS" +.sp +.nf +CHECKPOINT +.fi +.SH "DESCRIPTION" +.PP +A checkpoint is a point in the write\-ahead log sequence at which all data files have been updated to reflect the information in the log\&. All data files will be flushed to disk\&. Refer to +Section\ \&30.5 +for more details about what happens during a checkpoint\&. +.PP +The +\fBCHECKPOINT\fR +command forces an immediate checkpoint when the command is issued, without waiting for a regular checkpoint scheduled by the system (controlled by the settings in +Section\ \&20.5.2)\&. +\fBCHECKPOINT\fR +is not intended for use during normal operation\&. +.PP +If executed during recovery, the +\fBCHECKPOINT\fR +command will force a restartpoint (see +Section\ \&30.5) rather than writing a new checkpoint\&. +.PP +Only superusers or users with the privileges of the +pg_checkpoint +role can call +\fBCHECKPOINT\fR\&. +.SH "COMPATIBILITY" +.PP +The +\fBCHECKPOINT\fR +command is a +PostgreSQL +language extension\&. diff --git a/doc/src/sgml/man7/CLOSE.7 b/doc/src/sgml/man7/CLOSE.7 new file mode 100644 index 0000000..ca25c83 --- /dev/null +++ b/doc/src/sgml/man7/CLOSE.7 @@ -0,0 +1,99 @@ +'\" t +.\" Title: CLOSE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CLOSE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CLOSE \- close a cursor +.SH "SYNOPSIS" +.sp +.nf +CLOSE { \fIname\fR | ALL } +.fi +.SH "DESCRIPTION" +.PP +\fBCLOSE\fR +frees the resources associated with an open cursor\&. After the cursor is closed, no subsequent operations are allowed on it\&. A cursor should be closed when it is no longer needed\&. +.PP +Every non\-holdable open cursor is implicitly closed when a transaction is terminated by +\fBCOMMIT\fR +or +\fBROLLBACK\fR\&. A holdable cursor is implicitly closed if the transaction that created it aborts via +\fBROLLBACK\fR\&. If the creating transaction successfully commits, the holdable cursor remains open until an explicit +\fBCLOSE\fR +is executed, or the client disconnects\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of an open cursor to close\&. +.RE +.PP +ALL +.RS 4 +Close all open cursors\&. +.RE +.SH "NOTES" +.PP +PostgreSQL +does not have an explicit +\fBOPEN\fR +cursor statement; a cursor is considered open when it is declared\&. Use the +\fBDECLARE\fR +statement to declare a cursor\&. +.PP +You can see all available cursors by querying the +pg_cursors +system view\&. +.PP +If a cursor is closed after a savepoint which is later rolled back, the +\fBCLOSE\fR +is not rolled back; that is, the cursor remains closed\&. +.SH "EXAMPLES" +.PP +Close the cursor +liahona: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CLOSE liahona; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCLOSE\fR +is fully conforming with the SQL standard\&. +\fBCLOSE ALL\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +\fBDECLARE\fR(7), \fBFETCH\fR(7), \fBMOVE\fR(7) diff --git a/doc/src/sgml/man7/CLUSTER.7 b/doc/src/sgml/man7/CLUSTER.7 new file mode 100644 index 0000000..6453a8e --- /dev/null +++ b/doc/src/sgml/man7/CLUSTER.7 @@ -0,0 +1,219 @@ +'\" t +.\" Title: CLUSTER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CLUSTER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CLUSTER \- cluster a table according to an index +.SH "SYNOPSIS" +.sp +.nf +CLUSTER [VERBOSE] \fItable_name\fR [ USING \fIindex_name\fR ] +CLUSTER ( \fIoption\fR [, \&.\&.\&.] ) \fItable_name\fR [ USING \fIindex_name\fR ] +CLUSTER [VERBOSE] + +where \fIoption\fR can be one of: + + VERBOSE [ \fIboolean\fR ] +.fi +.SH "DESCRIPTION" +.PP +\fBCLUSTER\fR +instructs +PostgreSQL +to cluster the table specified by +\fItable_name\fR +based on the index specified by +\fIindex_name\fR\&. The index must already have been defined on +\fItable_name\fR\&. +.PP +When a table is clustered, it is physically reordered based on the index information\&. Clustering is a one\-time operation: when the table is subsequently updated, the changes are not clustered\&. That is, no attempt is made to store new or updated rows according to their index order\&. (If one wishes, one can periodically recluster by issuing the command again\&. Also, setting the table\*(Aqs +fillfactor +storage parameter to less than 100% can aid in preserving cluster ordering during updates, since updated rows are kept on the same page if enough space is available there\&.) +.PP +When a table is clustered, +PostgreSQL +remembers which index it was clustered by\&. The form +\fBCLUSTER \fR\fB\fItable_name\fR\fR +reclusters the table using the same index as before\&. You can also use the +CLUSTER +or +SET WITHOUT CLUSTER +forms of +\fBALTER TABLE\fR +to set the index to be used for future cluster operations, or to clear any previous setting\&. +.PP +\fBCLUSTER\fR +without any parameter reclusters all the previously\-clustered tables in the current database that the calling user owns, or all such tables if called by a superuser\&. This form of +\fBCLUSTER\fR +cannot be executed inside a transaction block\&. +.PP +When a table is being clustered, an +ACCESS EXCLUSIVE +lock is acquired on it\&. This prevents any other database operations (both reads and writes) from operating on the table until the +\fBCLUSTER\fR +is finished\&. +.SH "PARAMETERS" +.PP +\fItable_name\fR +.RS 4 +The name (possibly schema\-qualified) of a table\&. +.RE +.PP +\fIindex_name\fR +.RS 4 +The name of an index\&. +.RE +.PP +VERBOSE +.RS 4 +Prints a progress report as each table is clustered\&. +.RE +.PP +\fIboolean\fR +.RS 4 +Specifies whether the selected option should be turned on or off\&. You can write +TRUE, +ON, or +1 +to enable the option, and +FALSE, +OFF, or +0 +to disable it\&. The +\fIboolean\fR +value can also be omitted, in which case +TRUE +is assumed\&. +.RE +.SH "NOTES" +.PP +In cases where you are accessing single rows randomly within a table, the actual order of the data in the table is unimportant\&. However, if you tend to access some data more than others, and there is an index that groups them together, you will benefit from using +\fBCLUSTER\fR\&. If you are requesting a range of indexed values from a table, or a single indexed value that has multiple rows that match, +\fBCLUSTER\fR +will help because once the index identifies the table page for the first row that matches, all other rows that match are probably already on the same table page, and so you save disk accesses and speed up the query\&. +.PP +\fBCLUSTER\fR +can re\-sort the table using either an index scan on the specified index, or (if the index is a b\-tree) a sequential scan followed by sorting\&. It will attempt to choose the method that will be faster, based on planner cost parameters and available statistical information\&. +.PP +When an index scan is used, a temporary copy of the table is created that contains the table data in the index order\&. Temporary copies of each index on the table are created as well\&. Therefore, you need free space on disk at least equal to the sum of the table size and the index sizes\&. +.PP +When a sequential scan and sort is used, a temporary sort file is also created, so that the peak temporary space requirement is as much as double the table size, plus the index sizes\&. This method is often faster than the index scan method, but if the disk space requirement is intolerable, you can disable this choice by temporarily setting +enable_sort +to +off\&. +.PP +It is advisable to set +maintenance_work_mem +to a reasonably large value (but not more than the amount of RAM you can dedicate to the +\fBCLUSTER\fR +operation) before clustering\&. +.PP +Because the planner records statistics about the ordering of tables, it is advisable to run +\fBANALYZE\fR +on the newly clustered table\&. Otherwise, the planner might make poor choices of query plans\&. +.PP +Because +\fBCLUSTER\fR +remembers which indexes are clustered, one can cluster the tables one wants clustered manually the first time, then set up a periodic maintenance script that executes +\fBCLUSTER\fR +without any parameters, so that the desired tables are periodically reclustered\&. +.PP +Each backend running +\fBCLUSTER\fR +will report its progress in the +pg_stat_progress_cluster +view\&. See +Section\ \&28.4.4 +for details\&. +.PP +Clustering a partitioned table clusters each of its partitions using the partition of the specified partitioned index\&. When clustering a partitioned table, the index may not be omitted\&. +.SH "EXAMPLES" +.PP +Cluster the table +employees +on the basis of its index +employees_ind: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CLUSTER employees USING employees_ind; +.fi +.if n \{\ +.RE +.\} +.PP +Cluster the +employees +table using the same index that was used before: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CLUSTER employees; +.fi +.if n \{\ +.RE +.\} +.PP +Cluster all tables in the database that have previously been clustered: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CLUSTER; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBCLUSTER\fR +statement in the SQL standard\&. +.PP +The syntax +.sp +.if n \{\ +.RS 4 +.\} +.nf +CLUSTER \fIindex_name\fR ON \fItable_name\fR +.fi +.if n \{\ +.RE +.\} +.sp +is also supported for compatibility with pre\-8\&.3 +PostgreSQL +versions\&. +.SH "SEE ALSO" +\fBclusterdb\fR(1), Section\ \&28.4.4 diff --git a/doc/src/sgml/man7/COMMENT.7 b/doc/src/sgml/man7/COMMENT.7 new file mode 100644 index 0000000..293d0e9 --- /dev/null +++ b/doc/src/sgml/man7/COMMENT.7 @@ -0,0 +1,324 @@ +'\" t +.\" Title: COMMENT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "COMMENT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +COMMENT \- define or change the comment of an object +.SH "SYNOPSIS" +.sp +.nf +COMMENT ON +{ + ACCESS METHOD \fIobject_name\fR | + AGGREGATE \fIaggregate_name\fR ( \fIaggregate_signature\fR ) | + CAST (\fIsource_type\fR AS \fItarget_type\fR) | + COLLATION \fIobject_name\fR | + COLUMN \fIrelation_name\fR\&.\fIcolumn_name\fR | + CONSTRAINT \fIconstraint_name\fR ON \fItable_name\fR | + CONSTRAINT \fIconstraint_name\fR ON DOMAIN \fIdomain_name\fR | + CONVERSION \fIobject_name\fR | + DATABASE \fIobject_name\fR | + DOMAIN \fIobject_name\fR | + EXTENSION \fIobject_name\fR | + EVENT TRIGGER \fIobject_name\fR | + FOREIGN DATA WRAPPER \fIobject_name\fR | + FOREIGN TABLE \fIobject_name\fR | + FUNCTION \fIfunction_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + INDEX \fIobject_name\fR | + LARGE OBJECT \fIlarge_object_oid\fR | + MATERIALIZED VIEW \fIobject_name\fR | + OPERATOR \fIoperator_name\fR (\fIleft_type\fR, \fIright_type\fR) | + OPERATOR CLASS \fIobject_name\fR USING \fIindex_method\fR | + OPERATOR FAMILY \fIobject_name\fR USING \fIindex_method\fR | + POLICY \fIpolicy_name\fR ON \fItable_name\fR | + [ PROCEDURAL ] LANGUAGE \fIobject_name\fR | + PROCEDURE \fIprocedure_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + PUBLICATION \fIobject_name\fR | + ROLE \fIobject_name\fR | + ROUTINE \fIroutine_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + RULE \fIrule_name\fR ON \fItable_name\fR | + SCHEMA \fIobject_name\fR | + SEQUENCE \fIobject_name\fR | + SERVER \fIobject_name\fR | + STATISTICS \fIobject_name\fR | + SUBSCRIPTION \fIobject_name\fR | + TABLE \fIobject_name\fR | + TABLESPACE \fIobject_name\fR | + TEXT SEARCH CONFIGURATION \fIobject_name\fR | + TEXT SEARCH DICTIONARY \fIobject_name\fR | + TEXT SEARCH PARSER \fIobject_name\fR | + TEXT SEARCH TEMPLATE \fIobject_name\fR | + TRANSFORM FOR \fItype_name\fR LANGUAGE \fIlang_name\fR | + TRIGGER \fItrigger_name\fR ON \fItable_name\fR | + TYPE \fIobject_name\fR | + VIEW \fIobject_name\fR +} IS { \fIstring_literal\fR | NULL } + +where \fIaggregate_signature\fR is: + +* | +[ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] | +[ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBCOMMENT\fR +stores a comment about a database object\&. +.PP +Only one comment string is stored for each object, so to modify a comment, issue a new +\fBCOMMENT\fR +command for the same object\&. To remove a comment, write +NULL +in place of the text string\&. Comments are automatically dropped when their object is dropped\&. +.PP +A +SHARE UPDATE EXCLUSIVE +lock is acquired on the object to be commented\&. +.PP +For most kinds of object, only the object\*(Aqs owner can set the comment\&. Roles don\*(Aqt have owners, so the rule for +COMMENT ON ROLE +is that you must be superuser to comment on a superuser role, or have the +CREATEROLE +privilege to comment on non\-superuser roles\&. Likewise, access methods don\*(Aqt have owners either; you must be superuser to comment on an access method\&. Of course, a superuser can comment on anything\&. +.PP +Comments can be viewed using +psql\*(Aqs +\fB\ed\fR +family of commands\&. Other user interfaces to retrieve comments can be built atop the same built\-in functions that +psql +uses, namely +\fBobj_description\fR, +\fBcol_description\fR, and +\fBshobj_description\fR +(see +Table\ \&9.77)\&. +.SH "PARAMETERS" +.PP +\fIobject_name\fR +.br +\fIrelation_name\fR\&.\fIcolumn_name\fR +.br +\fIaggregate_name\fR +.br +\fIconstraint_name\fR +.br +\fIfunction_name\fR +.br +\fIoperator_name\fR +.br +\fIpolicy_name\fR +.br +\fIprocedure_name\fR +.br +\fIroutine_name\fR +.br +\fIrule_name\fR +.br +\fItrigger_name\fR +.RS 4 +The name of the object to be commented\&. Names of objects that reside in schemas (tables, functions, etc\&.) can be schema\-qualified\&. When commenting on a column, +\fIrelation_name\fR +must refer to a table, view, composite type, or foreign table\&. +.RE +.PP +\fItable_name\fR +.br +\fIdomain_name\fR +.RS 4 +When creating a comment on a constraint, a trigger, a rule or a policy these parameters specify the name of the table or domain on which that object is defined\&. +.RE +.PP +\fIsource_type\fR +.RS 4 +The name of the source data type of the cast\&. +.RE +.PP +\fItarget_type\fR +.RS 4 +The name of the target data type of the cast\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of a function, procedure, or aggregate argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. Note that +\fBCOMMENT\fR +does not actually pay any attention to +OUT +arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the +IN, +INOUT, and +VARIADIC +arguments\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of a function, procedure, or aggregate argument\&. Note that +\fBCOMMENT\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type of a function, procedure, or aggregate argument\&. +.RE +.PP +\fIlarge_object_oid\fR +.RS 4 +The OID of the large object\&. +.RE +.PP +\fIleft_type\fR +.br +\fIright_type\fR +.RS 4 +The data type(s) of the operator\*(Aqs arguments (optionally schema\-qualified)\&. Write +NONE +for the missing argument of a prefix operator\&. +.RE +.PP +PROCEDURAL +.RS 4 +This is a noise word\&. +.RE +.PP +\fItype_name\fR +.RS 4 +The name of the data type of the transform\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the language of the transform\&. +.RE +.PP +\fIstring_literal\fR +.RS 4 +The new comment contents, written as a string literal\&. +.RE +.PP +NULL +.RS 4 +Write +NULL +to drop the comment\&. +.RE +.SH "NOTES" +.PP +There is presently no security mechanism for viewing comments: any user connected to a database can see all the comments for objects in that database\&. For shared objects such as databases, roles, and tablespaces, comments are stored globally so any user connected to any database in the cluster can see all the comments for shared objects\&. Therefore, don\*(Aqt put security\-critical information in comments\&. +.SH "EXAMPLES" +.PP +Attach a comment to the table +mytable: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COMMENT ON TABLE mytable IS \*(AqThis is my table\&.\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +Remove it again: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COMMENT ON TABLE mytable IS NULL; +.fi +.if n \{\ +.RE +.\} +.PP +Some more examples: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COMMENT ON ACCESS METHOD gin IS \*(AqGIN index access method\*(Aq; +COMMENT ON AGGREGATE my_aggregate (double precision) IS \*(AqComputes sample variance\*(Aq; +COMMENT ON CAST (text AS int4) IS \*(AqAllow casts from text to int4\*(Aq; +COMMENT ON COLLATION "fr_CA" IS \*(AqCanadian French\*(Aq; +COMMENT ON COLUMN my_table\&.my_column IS \*(AqEmployee ID number\*(Aq; +COMMENT ON CONVERSION my_conv IS \*(AqConversion to UTF8\*(Aq; +COMMENT ON CONSTRAINT bar_col_cons ON bar IS \*(AqConstrains column col\*(Aq; +COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS \*(AqConstrains col of domain\*(Aq; +COMMENT ON DATABASE my_database IS \*(AqDevelopment Database\*(Aq; +COMMENT ON DOMAIN my_domain IS \*(AqEmail Address Domain\*(Aq; +COMMENT ON EVENT TRIGGER abort_ddl IS \*(AqAborts all DDL commands\*(Aq; +COMMENT ON EXTENSION hstore IS \*(Aqimplements the hstore data type\*(Aq; +COMMENT ON FOREIGN DATA WRAPPER mywrapper IS \*(Aqmy foreign data wrapper\*(Aq; +COMMENT ON FOREIGN TABLE my_foreign_table IS \*(AqEmployee Information in other database\*(Aq; +COMMENT ON FUNCTION my_function (timestamp) IS \*(AqReturns Roman Numeral\*(Aq; +COMMENT ON INDEX my_index IS \*(AqEnforces uniqueness on employee ID\*(Aq; +COMMENT ON LANGUAGE plpython IS \*(AqPython support for stored procedures\*(Aq; +COMMENT ON LARGE OBJECT 346344 IS \*(AqPlanning document\*(Aq; +COMMENT ON MATERIALIZED VIEW my_matview IS \*(AqSummary of order history\*(Aq; +COMMENT ON OPERATOR ^ (text, text) IS \*(AqPerforms intersection of two texts\*(Aq; +COMMENT ON OPERATOR \- (NONE, integer) IS \*(AqUnary minus\*(Aq; +COMMENT ON OPERATOR CLASS int4ops USING btree IS \*(Aq4 byte integer operators for btrees\*(Aq; +COMMENT ON OPERATOR FAMILY integer_ops USING btree IS \*(Aqall integer operators for btrees\*(Aq; +COMMENT ON POLICY my_policy ON mytable IS \*(AqFilter rows by users\*(Aq; +COMMENT ON PROCEDURE my_proc (integer, integer) IS \*(AqRuns a report\*(Aq; +COMMENT ON PUBLICATION alltables IS \*(AqPublishes all operations on all tables\*(Aq; +COMMENT ON ROLE my_role IS \*(AqAdministration group for finance tables\*(Aq; +COMMENT ON ROUTINE my_routine (integer, integer) IS \*(AqRuns a routine (which is a function or procedure)\*(Aq; +COMMENT ON RULE my_rule ON my_table IS \*(AqLogs updates of employee records\*(Aq; +COMMENT ON SCHEMA my_schema IS \*(AqDepartmental data\*(Aq; +COMMENT ON SEQUENCE my_sequence IS \*(AqUsed to generate primary keys\*(Aq; +COMMENT ON SERVER myserver IS \*(Aqmy foreign server\*(Aq; +COMMENT ON STATISTICS my_statistics IS \*(AqImproves planner row estimations\*(Aq; +COMMENT ON SUBSCRIPTION alltables IS \*(AqSubscription for all operations on all tables\*(Aq; +COMMENT ON TABLE my_schema\&.my_table IS \*(AqEmployee Information\*(Aq; +COMMENT ON TABLESPACE my_tablespace IS \*(AqTablespace for indexes\*(Aq; +COMMENT ON TEXT SEARCH CONFIGURATION my_config IS \*(AqSpecial word filtering\*(Aq; +COMMENT ON TEXT SEARCH DICTIONARY swedish IS \*(AqSnowball stemmer for Swedish language\*(Aq; +COMMENT ON TEXT SEARCH PARSER my_parser IS \*(AqSplits text into words\*(Aq; +COMMENT ON TEXT SEARCH TEMPLATE snowball IS \*(AqSnowball stemmer\*(Aq; +COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS \*(AqTransform between hstore and Python dict\*(Aq; +COMMENT ON TRIGGER my_trigger ON my_table IS \*(AqUsed for RI\*(Aq; +COMMENT ON TYPE complex IS \*(AqComplex number data type\*(Aq; +COMMENT ON VIEW my_view IS \*(AqView of departmental costs\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBCOMMENT\fR +command in the SQL standard\&. diff --git a/doc/src/sgml/man7/COMMIT.7 b/doc/src/sgml/man7/COMMIT.7 new file mode 100644 index 0000000..9ef60c8 --- /dev/null +++ b/doc/src/sgml/man7/COMMIT.7 @@ -0,0 +1,89 @@ +'\" t +.\" Title: COMMIT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "COMMIT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +COMMIT \- commit the current transaction +.SH "SYNOPSIS" +.sp +.nf +COMMIT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] +.fi +.SH "DESCRIPTION" +.PP +\fBCOMMIT\fR +commits the current transaction\&. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs\&. +.SH "PARAMETERS" +.PP +WORK +.br +TRANSACTION +.RS 4 +Optional key words\&. They have no effect\&. +.RE +.PP +AND CHAIN +.RS 4 +If +AND CHAIN +is specified, a new transaction is immediately started with the same transaction characteristics (see +SET TRANSACTION (\fBSET_TRANSACTION\fR(7))) as the just finished one\&. Otherwise, no new transaction is started\&. +.RE +.SH "NOTES" +.PP +Use +\fBROLLBACK\fR(7) +to abort a transaction\&. +.PP +Issuing +\fBCOMMIT\fR +when not inside a transaction does no harm, but it will provoke a warning message\&. +\fBCOMMIT AND CHAIN\fR +when not inside a transaction is an error\&. +.SH "EXAMPLES" +.PP +To commit the current transaction and make all changes permanent: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COMMIT; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The command +\fBCOMMIT\fR +conforms to the SQL standard\&. The form +COMMIT TRANSACTION +is a PostgreSQL extension\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBROLLBACK\fR(7) diff --git a/doc/src/sgml/man7/COMMIT_PREPARED.7 b/doc/src/sgml/man7/COMMIT_PREPARED.7 new file mode 100644 index 0000000..affc11c --- /dev/null +++ b/doc/src/sgml/man7/COMMIT_PREPARED.7 @@ -0,0 +1,77 @@ +'\" t +.\" Title: COMMIT PREPARED +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "COMMIT PREPARED" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +COMMIT_PREPARED \- commit a transaction that was earlier prepared for two\-phase commit +.SH "SYNOPSIS" +.sp +.nf +COMMIT PREPARED \fItransaction_id\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCOMMIT PREPARED\fR +commits a transaction that is in prepared state\&. +.SH "PARAMETERS" +.PP +\fItransaction_id\fR +.RS 4 +The transaction identifier of the transaction that is to be committed\&. +.RE +.SH "NOTES" +.PP +To commit a prepared transaction, you must be either the same user that executed the transaction originally, or a superuser\&. But you do not have to be in the same session that executed the transaction\&. +.PP +This command cannot be executed inside a transaction block\&. The prepared transaction is committed immediately\&. +.PP +All currently available prepared transactions are listed in the +pg_prepared_xacts +system view\&. +.SH "EXAMPLES" +.PP +Commit the transaction identified by the transaction identifier +foobar: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COMMIT PREPARED \*(Aqfoobar\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCOMMIT PREPARED\fR +is a +PostgreSQL +extension\&. It is intended for use by external transaction management systems, some of which are covered by standards (such as X/Open XA), but the SQL side of those systems is not standardized\&. +.SH "SEE ALSO" +PREPARE TRANSACTION (\fBPREPARE_TRANSACTION\fR(7)), ROLLBACK PREPARED (\fBROLLBACK_PREPARED\fR(7)) diff --git a/doc/src/sgml/man7/COPY.7 b/doc/src/sgml/man7/COPY.7 new file mode 100644 index 0000000..127bcbb --- /dev/null +++ b/doc/src/sgml/man7/COPY.7 @@ -0,0 +1,1006 @@ +'\" t +.\" Title: COPY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "COPY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +COPY \- copy data between a file and a table +.SH "SYNOPSIS" +.sp +.nf +COPY \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] + FROM { \*(Aq\fIfilename\fR\*(Aq | PROGRAM \*(Aq\fIcommand\fR\*(Aq | STDIN } + [ [ WITH ] ( \fIoption\fR [, \&.\&.\&.] ) ] + [ WHERE \fIcondition\fR ] + +COPY { \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] | ( \fIquery\fR ) } + TO { \*(Aq\fIfilename\fR\*(Aq | PROGRAM \*(Aq\fIcommand\fR\*(Aq | STDOUT } + [ [ WITH ] ( \fIoption\fR [, \&.\&.\&.] ) ] + +where \fIoption\fR can be one of: + + FORMAT \fIformat_name\fR + FREEZE [ \fIboolean\fR ] + DELIMITER \*(Aq\fIdelimiter_character\fR\*(Aq + NULL \*(Aq\fInull_string\fR\*(Aq + HEADER [ \fIboolean\fR | MATCH ] + QUOTE \*(Aq\fIquote_character\fR\*(Aq + ESCAPE \*(Aq\fIescape_character\fR\*(Aq + FORCE_QUOTE { ( \fIcolumn_name\fR [, \&.\&.\&.] ) | * } + FORCE_NOT_NULL ( \fIcolumn_name\fR [, \&.\&.\&.] ) + FORCE_NULL ( \fIcolumn_name\fR [, \&.\&.\&.] ) + ENCODING \*(Aq\fIencoding_name\fR\*(Aq +.fi +.SH "DESCRIPTION" +.PP +\fBCOPY\fR +moves data between +PostgreSQL +tables and standard file\-system files\&. +\fBCOPY TO\fR +copies the contents of a table +\fIto\fR +a file, while +\fBCOPY FROM\fR +copies data +\fIfrom\fR +a file to a table (appending the data to whatever is in the table already)\&. +\fBCOPY TO\fR +can also copy the results of a +\fBSELECT\fR +query\&. +.PP +If a column list is specified, +\fBCOPY TO\fR +copies only the data in the specified columns to the file\&. For +\fBCOPY FROM\fR, each field in the file is inserted, in order, into the specified column\&. Table columns not specified in the +\fBCOPY FROM\fR +column list will receive their default values\&. +.PP +\fBCOPY\fR +with a file name instructs the +PostgreSQL +server to directly read from or write to a file\&. The file must be accessible by the +PostgreSQL +user (the user ID the server runs as) and the name must be specified from the viewpoint of the server\&. When +PROGRAM +is specified, the server executes the given command and reads from the standard output of the program, or writes to the standard input of the program\&. The command must be specified from the viewpoint of the server, and be executable by the +PostgreSQL +user\&. When +STDIN +or +STDOUT +is specified, data is transmitted via the connection between the client and the server\&. +.PP +Each backend running +\fBCOPY\fR +will report its progress in the +pg_stat_progress_copy +view\&. See +Section\ \&28.4.6 +for details\&. +.SH "PARAMETERS" +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of an existing table\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +An optional list of columns to be copied\&. If no column list is specified, all columns of the table except generated columns will be copied\&. +.RE +.PP +\fIquery\fR +.RS 4 +A +\fBSELECT\fR, +\fBVALUES\fR, +\fBINSERT\fR, +\fBUPDATE\fR, or +\fBDELETE\fR +command whose results are to be copied\&. Note that parentheses are required around the query\&. +.sp +For +\fBINSERT\fR, +\fBUPDATE\fR +and +\fBDELETE\fR +queries a RETURNING clause must be provided, and the target relation must not have a conditional rule, nor an +ALSO +rule, nor an +INSTEAD +rule that expands to multiple statements\&. +.RE +.PP +\fIfilename\fR +.RS 4 +The path name of the input or output file\&. An input file name can be an absolute or relative path, but an output file name must be an absolute path\&. Windows users might need to use an +E\*(Aq\*(Aq +string and double any backslashes used in the path name\&. +.RE +.PP +PROGRAM +.RS 4 +A command to execute\&. In +\fBCOPY FROM\fR, the input is read from standard output of the command, and in +\fBCOPY TO\fR, the output is written to the standard input of the command\&. +.sp +Note that the command is invoked by the shell, so if you need to pass any arguments to shell command that come from an untrusted source, you must be careful to strip or escape any special characters that might have a special meaning for the shell\&. For security reasons, it is best to use a fixed command string, or at least avoid passing any user input in it\&. +.RE +.PP +STDIN +.RS 4 +Specifies that input comes from the client application\&. +.RE +.PP +STDOUT +.RS 4 +Specifies that output goes to the client application\&. +.RE +.PP +\fIboolean\fR +.RS 4 +Specifies whether the selected option should be turned on or off\&. You can write +TRUE, +ON, or +1 +to enable the option, and +FALSE, +OFF, or +0 +to disable it\&. The +\fIboolean\fR +value can also be omitted, in which case +TRUE +is assumed\&. +.RE +.PP +FORMAT +.RS 4 +Selects the data format to be read or written: +text, +csv +(Comma Separated Values), or +binary\&. The default is +text\&. +.RE +.PP +FREEZE +.RS 4 +Requests copying the data with rows already frozen, just as they would be after running the +\fBVACUUM FREEZE\fR +command\&. This is intended as a performance option for initial data loading\&. Rows will be frozen only if the table being loaded has been created or truncated in the current subtransaction, there are no cursors open and there are no older snapshots held by this transaction\&. It is currently not possible to perform a +\fBCOPY FREEZE\fR +on a partitioned table\&. +.sp +Note that all other sessions will immediately be able to see the data once it has been successfully loaded\&. This violates the normal rules of MVCC visibility and users specifying should be aware of the potential problems this might cause\&. +.RE +.PP +DELIMITER +.RS 4 +Specifies the character that separates columns within each row (line) of the file\&. The default is a tab character in text format, a comma in +CSV +format\&. This must be a single one\-byte character\&. This option is not allowed when using +binary +format\&. +.RE +.PP +NULL +.RS 4 +Specifies the string that represents a null value\&. The default is +\eN +(backslash\-N) in text format, and an unquoted empty string in +CSV +format\&. You might prefer an empty string even in text format for cases where you don\*(Aqt want to distinguish nulls from empty strings\&. This option is not allowed when using +binary +format\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +When using +\fBCOPY FROM\fR, any data item that matches this string will be stored as a null value, so you should make sure that you use the same string as you used with +\fBCOPY TO\fR\&. +.sp .5v +.RE +.RE +.PP +HEADER +.RS 4 +Specifies that the file contains a header line with the names of each column in the file\&. On output, the first line contains the column names from the table\&. On input, the first line is discarded when this option is set to +true +(or equivalent Boolean value)\&. If this option is set to +MATCH, the number and names of the columns in the header line must match the actual column names of the table, in order; otherwise an error is raised\&. This option is not allowed when using +binary +format\&. The +MATCH +option is only valid for +\fBCOPY FROM\fR +commands\&. +.RE +.PP +QUOTE +.RS 4 +Specifies the quoting character to be used when a data value is quoted\&. The default is double\-quote\&. This must be a single one\-byte character\&. This option is allowed only when using +CSV +format\&. +.RE +.PP +ESCAPE +.RS 4 +Specifies the character that should appear before a data character that matches the +QUOTE +value\&. The default is the same as the +QUOTE +value (so that the quoting character is doubled if it appears in the data)\&. This must be a single one\-byte character\&. This option is allowed only when using +CSV +format\&. +.RE +.PP +FORCE_QUOTE +.RS 4 +Forces quoting to be used for all non\-NULL +values in each specified column\&. +NULL +output is never quoted\&. If +* +is specified, non\-NULL +values will be quoted in all columns\&. This option is allowed only in +\fBCOPY TO\fR, and only when using +CSV +format\&. +.RE +.PP +FORCE_NOT_NULL +.RS 4 +Do not match the specified columns\*(Aq values against the null string\&. In the default case where the null string is empty, this means that empty values will be read as zero\-length strings rather than nulls, even when they are not quoted\&. This option is allowed only in +\fBCOPY FROM\fR, and only when using +CSV +format\&. +.RE +.PP +FORCE_NULL +.RS 4 +Match the specified columns\*(Aq values against the null string, even if it has been quoted, and if a match is found set the value to +NULL\&. In the default case where the null string is empty, this converts a quoted empty string into NULL\&. This option is allowed only in +\fBCOPY FROM\fR, and only when using +CSV +format\&. +.RE +.PP +ENCODING +.RS 4 +Specifies that the file is encoded in the +\fIencoding_name\fR\&. If this option is omitted, the current client encoding is used\&. See the Notes below for more details\&. +.RE +.PP +WHERE +.RS 4 +The optional +WHERE +clause has the general form +.sp +.if n \{\ +.RS 4 +.\} +.nf +WHERE \fIcondition\fR +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIcondition\fR +is any expression that evaluates to a result of type +boolean\&. Any row that does not satisfy this condition will not be inserted to the table\&. A row satisfies the condition if it returns true when the actual row values are substituted for any variable references\&. +.sp +Currently, subqueries are not allowed in +WHERE +expressions, and the evaluation does not see any changes made by the +\fBCOPY\fR +itself (this matters when the expression contains calls to +VOLATILE +functions)\&. +.RE +.SH "OUTPUTS" +.PP +On successful completion, a +\fBCOPY\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY \fIcount\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fIcount\fR +is the number of rows copied\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +psql +will print this command tag only if the command was not +COPY \&.\&.\&. TO STDOUT, or the equivalent +psql +meta\-command +\ecopy \&.\&.\&. to stdout\&. This is to prevent confusing the command tag with the data that was just printed\&. +.sp .5v +.RE +.SH "NOTES" +.PP +\fBCOPY TO\fR +can be used only with plain tables, not views, and does not copy rows from child tables or child partitions\&. For example, +COPY \fItable\fR TO +copies the same rows as +SELECT * FROM ONLY \fItable\fR\&. The syntax +COPY (SELECT * FROM \fItable\fR) TO \&.\&.\&. +can be used to dump all of the rows in an inheritance hierarchy, partitioned table, or view\&. +.PP +\fBCOPY FROM\fR +can be used with plain, foreign, or partitioned tables or with views that have +INSTEAD OF INSERT +triggers\&. +.PP +You must have select privilege on the table whose values are read by +\fBCOPY TO\fR, and insert privilege on the table into which values are inserted by +\fBCOPY FROM\fR\&. It is sufficient to have column privileges on the column(s) listed in the command\&. +.PP +If row\-level security is enabled for the table, the relevant +\fBSELECT\fR +policies will apply to +COPY \fItable\fR TO +statements\&. Currently, +\fBCOPY FROM\fR +is not supported for tables with row\-level security\&. Use equivalent +\fBINSERT\fR +statements instead\&. +.PP +Files named in a +\fBCOPY\fR +command are read or written directly by the server, not by the client application\&. Therefore, they must reside on or be accessible to the database server machine, not the client\&. They must be accessible to and readable or writable by the +PostgreSQL +user (the user ID the server runs as), not the client\&. Similarly, the command specified with +PROGRAM +is executed directly by the server, not by the client application, must be executable by the +PostgreSQL +user\&. +\fBCOPY\fR +naming a file or command is only allowed to database superusers or users who are granted one of the roles +pg_read_server_files, +pg_write_server_files, or +pg_execute_server_program, since it allows reading or writing any file or running a program that the server has privileges to access\&. +.PP +Do not confuse +\fBCOPY\fR +with the +psql +instruction +\fB\ecopy\fR\&. +\fB\ecopy\fR +invokes +\fBCOPY FROM STDIN\fR +or +\fBCOPY TO STDOUT\fR, and then fetches/stores the data in a file accessible to the +psql +client\&. Thus, file accessibility and access rights depend on the client rather than the server when +\fB\ecopy\fR +is used\&. +.PP +It is recommended that the file name used in +\fBCOPY\fR +always be specified as an absolute path\&. This is enforced by the server in the case of +\fBCOPY TO\fR, but for +\fBCOPY FROM\fR +you do have the option of reading from a file specified by a relative path\&. The path will be interpreted relative to the working directory of the server process (normally the cluster\*(Aqs data directory), not the client\*(Aqs working directory\&. +.PP +Executing a command with +PROGRAM +might be restricted by the operating system\*(Aqs access control mechanisms, such as SELinux\&. +.PP +\fBCOPY FROM\fR +will invoke any triggers and check constraints on the destination table\&. However, it will not invoke rules\&. +.PP +For identity columns, the +\fBCOPY FROM\fR +command will always write the column values provided in the input data, like the +\fBINSERT\fR +option +OVERRIDING SYSTEM VALUE\&. +.PP +\fBCOPY\fR +input and output is affected by +\fIDateStyle\fR\&. To ensure portability to other +PostgreSQL +installations that might use non\-default +\fIDateStyle\fR +settings, +\fIDateStyle\fR +should be set to +ISO +before using +\fBCOPY TO\fR\&. It is also a good idea to avoid dumping data with +\fIIntervalStyle\fR +set to +sql_standard, because negative interval values might be misinterpreted by a server that has a different setting for +\fIIntervalStyle\fR\&. +.PP +Input data is interpreted according to +ENCODING +option or the current client encoding, and output data is encoded in +ENCODING +or the current client encoding, even if the data does not pass through the client but is read from or written to a file directly by the server\&. +.PP +\fBCOPY\fR +stops operation at the first error\&. This should not lead to problems in the event of a +\fBCOPY TO\fR, but the target table will already have received earlier rows in a +\fBCOPY FROM\fR\&. These rows will not be visible or accessible, but they still occupy disk space\&. This might amount to a considerable amount of wasted disk space if the failure happened well into a large copy operation\&. You might wish to invoke +\fBVACUUM\fR +to recover the wasted space\&. +.PP +FORCE_NULL +and +FORCE_NOT_NULL +can be used simultaneously on the same column\&. This results in converting quoted null strings to null values and unquoted null strings to empty strings\&. +.SH "FILE FORMATS" +.SS "Text Format" +.PP +When the +text +format is used, the data read or written is a text file with one line per table row\&. Columns in a row are separated by the delimiter character\&. The column values themselves are strings generated by the output function, or acceptable to the input function, of each attribute\*(Aqs data type\&. The specified null string is used in place of columns that are null\&. +\fBCOPY FROM\fR +will raise an error if any line of the input file contains more or fewer columns than are expected\&. +.PP +End of data can be represented by a single line containing just backslash\-period (\e\&.)\&. An end\-of\-data marker is not necessary when reading from a file, since the end of file serves perfectly well; it is needed only when copying data to or from client applications using pre\-3\&.0 client protocol\&. +.PP +Backslash characters (\e) can be used in the +\fBCOPY\fR +data to quote data characters that might otherwise be taken as row or column delimiters\&. In particular, the following characters +\fImust\fR +be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character\&. +.PP +The specified null string is sent by +\fBCOPY TO\fR +without adding any backslashes; conversely, +\fBCOPY FROM\fR +matches the input against the null string before removing backslashes\&. Therefore, a null string such as +\eN +cannot be confused with the actual data value +\eN +(which would be represented as +\e\eN)\&. +.PP +The following special backslash sequences are recognized by +\fBCOPY FROM\fR: +.TS +allbox tab(:); +lB lB. +T{ +Sequence +T}:T{ +Represents +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +\eb +T}:T{ +Backspace (ASCII 8) +T} +T{ +\ef +T}:T{ +Form feed (ASCII 12) +T} +T{ +\en +T}:T{ +Newline (ASCII 10) +T} +T{ +\er +T}:T{ +Carriage return (ASCII 13) +T} +T{ +\et +T}:T{ +Tab (ASCII 9) +T} +T{ +\ev +T}:T{ +Vertical tab (ASCII 11) +T} +T{ +\e\fIdigits\fR +T}:T{ +Backslash followed by one to three octal digits specifies + the byte with that numeric code +T} +T{ +\ex\fIdigits\fR +T}:T{ +Backslash x followed by one or two hex digits specifies + the byte with that numeric code +T} +.TE +.sp 1 +Presently, +\fBCOPY TO\fR +will never emit an octal or hex\-digits backslash sequence, but it does use the other sequences listed above for those control characters\&. +.PP +Any other backslashed character that is not mentioned in the above table will be taken to represent itself\&. However, beware of adding backslashes unnecessarily, since that might accidentally produce a string matching the end\-of\-data marker (\e\&.) or the null string (\eN +by default)\&. These strings will be recognized before any other backslash processing is done\&. +.PP +It is strongly recommended that applications generating +\fBCOPY\fR +data convert data newlines and carriage returns to the +\en +and +\er +sequences respectively\&. At present it is possible to represent a data carriage return by a backslash and carriage return, and to represent a data newline by a backslash and newline\&. However, these representations might not be accepted in future releases\&. They are also highly vulnerable to corruption if the +\fBCOPY\fR +file is transferred across different machines (for example, from Unix to Windows or vice versa)\&. +.PP +All backslash sequences are interpreted after encoding conversion\&. The bytes specified with the octal and hex\-digit backslash sequences must form valid characters in the database encoding\&. +.PP +\fBCOPY TO\fR +will terminate each row with a Unix\-style newline (\(lq\en\(rq)\&. Servers running on Microsoft Windows instead output carriage return/newline (\(lq\er\en\(rq), but only for +\fBCOPY\fR +to a server file; for consistency across platforms, +\fBCOPY TO STDOUT\fR +always sends +\(lq\en\(rq +regardless of server platform\&. +\fBCOPY FROM\fR +can handle lines ending with newlines, carriage returns, or carriage return/newlines\&. To reduce the risk of error due to un\-backslashed newlines or carriage returns that were meant as data, +\fBCOPY FROM\fR +will complain if the line endings in the input are not all alike\&. +.SS "CSV Format" +.PP +This format option is used for importing and exporting the Comma Separated Value (CSV) file format used by many other programs, such as spreadsheets\&. Instead of the escaping rules used by +PostgreSQL\*(Aqs standard text format, it produces and recognizes the common CSV escaping mechanism\&. +.PP +The values in each record are separated by the +DELIMITER +character\&. If the value contains the delimiter character, the +QUOTE +character, the +NULL +string, a carriage return, or line feed character, then the whole value is prefixed and suffixed by the +QUOTE +character, and any occurrence within the value of a +QUOTE +character or the +ESCAPE +character is preceded by the escape character\&. You can also use +FORCE_QUOTE +to force quotes when outputting non\-NULL +values in specific columns\&. +.PP +The +CSV +format has no standard way to distinguish a +NULL +value from an empty string\&. +PostgreSQL\*(Aqs +\fBCOPY\fR +handles this by quoting\&. A +NULL +is output as the +NULL +parameter string and is not quoted, while a non\-NULL +value matching the +NULL +parameter string is quoted\&. For example, with the default settings, a +NULL +is written as an unquoted empty string, while an empty string data value is written with double quotes ("")\&. Reading values follows similar rules\&. You can use +FORCE_NOT_NULL +to prevent +NULL +input comparisons for specific columns\&. You can also use +FORCE_NULL +to convert quoted null string data values to +NULL\&. +.PP +Because backslash is not a special character in the +CSV +format, +\e\&., the end\-of\-data marker, could also appear as a data value\&. To avoid any misinterpretation, a +\e\&. +data value appearing as a lone entry on a line is automatically quoted on output, and on input, if quoted, is not interpreted as the end\-of\-data marker\&. If you are loading a file created by another application that has a single unquoted column and might have a value of +\e\&., you might need to quote that value in the input file\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +In +CSV +format, all characters are significant\&. A quoted value surrounded by white space, or any characters other than +DELIMITER, will include those characters\&. This can cause errors if you import data from a system that pads +CSV +lines with white space out to some fixed width\&. If such a situation arises you might need to preprocess the +CSV +file to remove the trailing white space, before importing the data into +PostgreSQL\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +CSV format will both recognize and produce CSV files with quoted values containing embedded carriage returns and line feeds\&. Thus the files are not strictly one line per table row like text\-format files\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +Many programs produce strange and occasionally perverse CSV files, so the file format is more a convention than a standard\&. Thus you might encounter some files that cannot be imported using this mechanism, and +\fBCOPY\fR +might produce files that other programs cannot process\&. +.sp .5v +.RE +.SS "Binary Format" +.PP +The +binary +format option causes all data to be stored/read as binary format rather than as text\&. It is somewhat faster than the text and +CSV +formats, but a binary\-format file is less portable across machine architectures and +PostgreSQL +versions\&. Also, the binary format is very data type specific; for example it will not work to output binary data from a +smallint +column and read it into an +integer +column, even though that would work fine in text format\&. +.PP +The +binary +file format consists of a file header, zero or more tuples containing the row data, and a file trailer\&. Headers and data are in network byte order\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +PostgreSQL +releases before 7\&.4 used a different binary file format\&. +.sp .5v +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBFile Header\fR +.RS 4 +.PP +The file header consists of 15 bytes of fixed fields, followed by a variable\-length header extension area\&. The fixed fields are: +.PP +Signature +.RS 4 +11\-byte sequence +PGCOPY\en\e377\er\en\e0 +\(em note that the zero byte is a required part of the signature\&. (The signature is designed to allow easy identification of files that have been munged by a non\-8\-bit\-clean transfer\&. This signature will be changed by end\-of\-line\-translation filters, dropped zero bytes, dropped high bits, or parity changes\&.) +.RE +.PP +Flags field +.RS 4 +32\-bit integer bit mask to denote important aspects of the file format\&. Bits are numbered from 0 (LSB) to 31 (MSB)\&. Note that this field is stored in network byte order (most significant byte first), as are all the integer fields used in the file format\&. Bits 16\(en31 are reserved to denote critical file format issues; a reader should abort if it finds an unexpected bit set in this range\&. Bits 0\(en15 are reserved to signal backwards\-compatible format issues; a reader should simply ignore any unexpected bits set in this range\&. Currently only one flag bit is defined, and the rest must be zero: +.PP +Bit 16 +.RS 4 +If 1, OIDs are included in the data; if 0, not\&. Oid system columns are not supported in +PostgreSQL +anymore, but the format still contains the indicator\&. +.RE +.RE +.PP +Header extension area length +.RS 4 +32\-bit integer, length in bytes of remainder of header, not including self\&. Currently, this is zero, and the first tuple follows immediately\&. Future changes to the format might allow additional data to be present in the header\&. A reader should silently skip over any header extension data it does not know what to do with\&. +.RE +.PP +The header extension area is envisioned to contain a sequence of self\-identifying chunks\&. The flags field is not intended to tell readers what is in the extension area\&. Specific design of header extension contents is left for a later release\&. +.PP +This design allows for both backwards\-compatible header additions (add header extension chunks, or set low\-order flag bits) and non\-backwards\-compatible changes (set high\-order flag bits to signal such changes, and add supporting data to the extension area if needed)\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTuples\fR +.RS 4 +.PP +Each tuple begins with a 16\-bit integer count of the number of fields in the tuple\&. (Presently, all tuples in a table will have the same count, but that might not always be true\&.) Then, repeated for each field in the tuple, there is a 32\-bit length word followed by that many bytes of field data\&. (The length word does not include itself, and can be zero\&.) As a special case, \-1 indicates a NULL field value\&. No value bytes follow in the NULL case\&. +.PP +There is no alignment padding or any other extra data between fields\&. +.PP +Presently, all data values in a binary\-format file are assumed to be in binary format (format code one)\&. It is anticipated that a future extension might add a header field that allows per\-column format codes to be specified\&. +.PP +To determine the appropriate binary format for the actual tuple data you should consult the +PostgreSQL +source, in particular the +\fB*send\fR +and +\fB*recv\fR +functions for each column\*(Aqs data type (typically these functions are found in the +src/backend/utils/adt/ +directory of the source distribution)\&. +.PP +If OIDs are included in the file, the OID field immediately follows the field\-count word\&. It is a normal field except that it\*(Aqs not included in the field\-count\&. Note that oid system columns are not supported in current versions of +PostgreSQL\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBFile Trailer\fR +.RS 4 +.PP +The file trailer consists of a 16\-bit integer word containing \-1\&. This is easily distinguished from a tuple\*(Aqs field\-count word\&. +.PP +A reader should report an error if a field\-count word is neither \-1 nor the expected number of columns\&. This provides an extra check against somehow getting out of sync with the data\&. +.RE +.SH "EXAMPLES" +.PP +The following example copies a table to the client using the vertical bar (|) as the field delimiter: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY country TO STDOUT (DELIMITER \*(Aq|\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +To copy data from a file into the +country +table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY country FROM \*(Aq/usr1/proj/bray/sql/country_data\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To copy into a file just the countries whose names start with \*(AqA\*(Aq: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY (SELECT * FROM country WHERE country_name LIKE \*(AqA%\*(Aq) TO \*(Aq/usr1/proj/bray/sql/a_list_countries\&.copy\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To copy into a compressed file, you can pipe the output through an external compression program: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY country TO PROGRAM \*(Aqgzip > /usr1/proj/bray/sql/country_data\&.gz\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Here is a sample of data suitable for copying into a table from +STDIN: +.sp +.if n \{\ +.RS 4 +.\} +.nf +AF AFGHANISTAN +AL ALBANIA +DZ ALGERIA +ZM ZAMBIA +ZW ZIMBABWE +.fi +.if n \{\ +.RE +.\} +.sp +Note that the white space on each line is actually a tab character\&. +.PP +The following is the same data, output in binary format\&. The data is shown after filtering through the Unix utility +\fBod \-c\fR\&. The table has three columns; the first has type +char(2), the second has type +text, and the third has type +integer\&. All the rows have a null value in the third column\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +0000000 P G C O P Y \en 377 \er \en \e0 \e0 \e0 \e0 \e0 \e0 +0000020 \e0 \e0 \e0 \e0 003 \e0 \e0 \e0 002 A F \e0 \e0 \e0 013 A +0000040 F G H A N I S T A N 377 377 377 377 \e0 003 +0000060 \e0 \e0 \e0 002 A L \e0 \e0 \e0 007 A L B A N I +0000100 A 377 377 377 377 \e0 003 \e0 \e0 \e0 002 D Z \e0 \e0 \e0 +0000120 007 A L G E R I A 377 377 377 377 \e0 003 \e0 \e0 +0000140 \e0 002 Z M \e0 \e0 \e0 006 Z A M B I A 377 377 +0000160 377 377 \e0 003 \e0 \e0 \e0 002 Z W \e0 \e0 \e0 \eb Z I +0000200 M B A B W E 377 377 377 377 377 377 +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBCOPY\fR +statement in the SQL standard\&. +.PP +The following syntax was used before +PostgreSQL +version 9\&.0 and is still supported: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] + FROM { \*(Aq\fIfilename\fR\*(Aq | STDIN } + [ [ WITH ] + [ BINARY ] + [ DELIMITER [ AS ] \*(Aq\fIdelimiter_character\fR\*(Aq ] + [ NULL [ AS ] \*(Aq\fInull_string\fR\*(Aq ] + [ CSV [ HEADER ] + [ QUOTE [ AS ] \*(Aq\fIquote_character\fR\*(Aq ] + [ ESCAPE [ AS ] \*(Aq\fIescape_character\fR\*(Aq ] + [ FORCE NOT NULL \fIcolumn_name\fR [, \&.\&.\&.] ] ] ] + +COPY { \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] | ( \fIquery\fR ) } + TO { \*(Aq\fIfilename\fR\*(Aq | STDOUT } + [ [ WITH ] + [ BINARY ] + [ DELIMITER [ AS ] \*(Aq\fIdelimiter_character\fR\*(Aq ] + [ NULL [ AS ] \*(Aq\fInull_string\fR\*(Aq ] + [ CSV [ HEADER ] + [ QUOTE [ AS ] \*(Aq\fIquote_character\fR\*(Aq ] + [ ESCAPE [ AS ] \*(Aq\fIescape_character\fR\*(Aq ] + [ FORCE QUOTE { \fIcolumn_name\fR [, \&.\&.\&.] | * } ] ] ] +.fi +.if n \{\ +.RE +.\} +.sp +Note that in this syntax, +BINARY +and +CSV +are treated as independent keywords, not as arguments of a +FORMAT +option\&. +.PP +The following syntax was used before +PostgreSQL +version 7\&.3 and is still supported: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COPY [ BINARY ] \fItable_name\fR + FROM { \*(Aq\fIfilename\fR\*(Aq | STDIN } + [ [USING] DELIMITERS \*(Aq\fIdelimiter_character\fR\*(Aq ] + [ WITH NULL AS \*(Aq\fInull_string\fR\*(Aq ] + +COPY [ BINARY ] \fItable_name\fR + TO { \*(Aq\fIfilename\fR\*(Aq | STDOUT } + [ [USING] DELIMITERS \*(Aq\fIdelimiter_character\fR\*(Aq ] + [ WITH NULL AS \*(Aq\fInull_string\fR\*(Aq ] +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +Section\ \&28.4.6 diff --git a/doc/src/sgml/man7/CREATE_ACCESS_METHOD.7 b/doc/src/sgml/man7/CREATE_ACCESS_METHOD.7 new file mode 100644 index 0000000..92ee214 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_ACCESS_METHOD.7 @@ -0,0 +1,102 @@ +'\" t +.\" Title: CREATE ACCESS METHOD +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE ACCESS METHOD" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_ACCESS_METHOD \- define a new access method +.SH "SYNOPSIS" +.sp +.nf +CREATE ACCESS METHOD \fIname\fR + TYPE \fIaccess_method_type\fR + HANDLER \fIhandler_function\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE ACCESS METHOD\fR +creates a new access method\&. +.PP +The access method name must be unique within the database\&. +.PP +Only superusers can define new access methods\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the access method to be created\&. +.RE +.PP +\fIaccess_method_type\fR +.RS 4 +This clause specifies the type of access method to define\&. Only +TABLE +and +INDEX +are supported at present\&. +.RE +.PP +\fIhandler_function\fR +.RS 4 +\fIhandler_function\fR +is the name (possibly schema\-qualified) of a previously registered function that represents the access method\&. The handler function must be declared to take a single argument of type +internal, and its return type depends on the type of access method; for +TABLE +access methods, it must be +table_am_handler +and for +INDEX +access methods, it must be +index_am_handler\&. The C\-level API that the handler function must implement varies depending on the type of access method\&. The table access method API is described in +Chapter\ \&63 +and the index access method API is described in +Chapter\ \&64\&. +.RE +.SH "EXAMPLES" +.PP +Create an index access method +heptree +with handler function +heptree_handler: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE ACCESS METHOD\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +DROP ACCESS METHOD (\fBDROP_ACCESS_METHOD\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), CREATE OPERATOR FAMILY (\fBCREATE_OPERATOR_FAMILY\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_AGGREGATE.7 b/doc/src/sgml/man7/CREATE_AGGREGATE.7 new file mode 100644 index 0000000..3c158fc --- /dev/null +++ b/doc/src/sgml/man7/CREATE_AGGREGATE.7 @@ -0,0 +1,552 @@ +'\" t +.\" Title: CREATE AGGREGATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE AGGREGATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_AGGREGATE \- define a new aggregate function +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] AGGREGATE \fIname\fR ( [ \fIargmode\fR ] [ \fIargname\fR ] \fIarg_data_type\fR [ , \&.\&.\&. ] ) ( + SFUNC = \fIsfunc\fR, + STYPE = \fIstate_data_type\fR + [ , SSPACE = \fIstate_data_size\fR ] + [ , FINALFUNC = \fIffunc\fR ] + [ , FINALFUNC_EXTRA ] + [ , FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ] + [ , COMBINEFUNC = \fIcombinefunc\fR ] + [ , SERIALFUNC = \fIserialfunc\fR ] + [ , DESERIALFUNC = \fIdeserialfunc\fR ] + [ , INITCOND = \fIinitial_condition\fR ] + [ , MSFUNC = \fImsfunc\fR ] + [ , MINVFUNC = \fIminvfunc\fR ] + [ , MSTYPE = \fImstate_data_type\fR ] + [ , MSSPACE = \fImstate_data_size\fR ] + [ , MFINALFUNC = \fImffunc\fR ] + [ , MFINALFUNC_EXTRA ] + [ , MFINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ] + [ , MINITCOND = \fIminitial_condition\fR ] + [ , SORTOP = \fIsort_operator\fR ] + [ , PARALLEL = { SAFE | RESTRICTED | UNSAFE } ] +) + +CREATE [ OR REPLACE ] AGGREGATE \fIname\fR ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIarg_data_type\fR [ , \&.\&.\&. ] ] + ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIarg_data_type\fR [ , \&.\&.\&. ] ) ( + SFUNC = \fIsfunc\fR, + STYPE = \fIstate_data_type\fR + [ , SSPACE = \fIstate_data_size\fR ] + [ , FINALFUNC = \fIffunc\fR ] + [ , FINALFUNC_EXTRA ] + [ , FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ] + [ , INITCOND = \fIinitial_condition\fR ] + [ , PARALLEL = { SAFE | RESTRICTED | UNSAFE } ] + [ , HYPOTHETICAL ] +) + +or the old syntax + +CREATE [ OR REPLACE ] AGGREGATE \fIname\fR ( + BASETYPE = \fIbase_type\fR, + SFUNC = \fIsfunc\fR, + STYPE = \fIstate_data_type\fR + [ , SSPACE = \fIstate_data_size\fR ] + [ , FINALFUNC = \fIffunc\fR ] + [ , FINALFUNC_EXTRA ] + [ , FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ] + [ , COMBINEFUNC = \fIcombinefunc\fR ] + [ , SERIALFUNC = \fIserialfunc\fR ] + [ , DESERIALFUNC = \fIdeserialfunc\fR ] + [ , INITCOND = \fIinitial_condition\fR ] + [ , MSFUNC = \fImsfunc\fR ] + [ , MINVFUNC = \fIminvfunc\fR ] + [ , MSTYPE = \fImstate_data_type\fR ] + [ , MSSPACE = \fImstate_data_size\fR ] + [ , MFINALFUNC = \fImffunc\fR ] + [ , MFINALFUNC_EXTRA ] + [ , MFINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } ] + [ , MINITCOND = \fIminitial_condition\fR ] + [ , SORTOP = \fIsort_operator\fR ] +) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE AGGREGATE\fR +defines a new aggregate function\&. +\fBCREATE OR REPLACE AGGREGATE\fR +will either define a new aggregate function or replace an existing definition\&. Some basic and commonly\-used aggregate functions are included with the distribution; they are documented in +Section\ \&9.21\&. If one defines new types or needs an aggregate function not already provided, then +\fBCREATE AGGREGATE\fR +can be used to provide the desired features\&. +.PP +When replacing an existing definition, the argument types, result type, and number of direct arguments may not be changed\&. Also, the new definition must be of the same kind (ordinary aggregate, ordered\-set aggregate, or hypothetical\-set aggregate) as the old one\&. +.PP +If a schema name is given (for example, +CREATE AGGREGATE myschema\&.myagg \&.\&.\&.) then the aggregate function is created in the specified schema\&. Otherwise it is created in the current schema\&. +.PP +An aggregate function is identified by its name and input data type(s)\&. Two aggregates in the same schema can have the same name if they operate on different input types\&. The name and input data type(s) of an aggregate must also be distinct from the name and input data type(s) of every ordinary function in the same schema\&. This behavior is identical to overloading of ordinary function names (see +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)))\&. +.PP +A simple aggregate function is made from one or two ordinary functions: a state transition function +\fIsfunc\fR, and an optional final calculation function +\fIffunc\fR\&. These are used as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIsfunc\fR( internal\-state, next\-data\-values ) \-\-\-> next\-internal\-state +\fIffunc\fR( internal\-state ) \-\-\-> aggregate\-value +.fi +.if n \{\ +.RE +.\} +.PP +PostgreSQL +creates a temporary variable of data type +\fIstype\fR +to hold the current internal state of the aggregate\&. At each input row, the aggregate argument value(s) are calculated and the state transition function is invoked with the current state value and the new argument value(s) to calculate a new internal state value\&. After all the rows have been processed, the final function is invoked once to calculate the aggregate\*(Aqs return value\&. If there is no final function then the ending state value is returned as\-is\&. +.PP +An aggregate function can provide an initial condition, that is, an initial value for the internal state value\&. This is specified and stored in the database as a value of type +text, but it must be a valid external representation of a constant of the state value data type\&. If it is not supplied then the state value starts out null\&. +.PP +If the state transition function is declared +\(lqstrict\(rq, then it cannot be called with null inputs\&. With such a transition function, aggregate execution behaves as follows\&. Rows with any null input values are ignored (the function is not called and the previous state value is retained)\&. If the initial state value is null, then at the first row with all\-nonnull input values, the first argument value replaces the state value, and the transition function is invoked at each subsequent row with all\-nonnull input values\&. This is handy for implementing aggregates like +\fBmax\fR\&. Note that this behavior is only available when +\fIstate_data_type\fR +is the same as the first +\fIarg_data_type\fR\&. When these types are different, you must supply a nonnull initial condition or use a nonstrict transition function\&. +.PP +If the state transition function is not strict, then it will be called unconditionally at each input row, and must deal with null inputs and null state values for itself\&. This allows the aggregate author to have full control over the aggregate\*(Aqs handling of null values\&. +.PP +If the final function is declared +\(lqstrict\(rq, then it will not be called when the ending state value is null; instead a null result will be returned automatically\&. (Of course this is just the normal behavior of strict functions\&.) In any case the final function has the option of returning a null value\&. For example, the final function for +\fBavg\fR +returns null when it sees there were zero input rows\&. +.PP +Sometimes it is useful to declare the final function as taking not just the state value, but extra parameters corresponding to the aggregate\*(Aqs input values\&. The main reason for doing this is if the final function is polymorphic and the state value\*(Aqs data type would be inadequate to pin down the result type\&. These extra parameters are always passed as NULL (and so the final function must not be strict when the +FINALFUNC_EXTRA +option is used), but nonetheless they are valid parameters\&. The final function could for example make use of +\fBget_fn_expr_argtype\fR +to identify the actual argument type in the current call\&. +.PP +An aggregate can optionally support +moving\-aggregate mode, as described in +Section\ \&38.12.1\&. This requires specifying the +MSFUNC, +MINVFUNC, and +MSTYPE +parameters, and optionally the +MSSPACE, +MFINALFUNC, +MFINALFUNC_EXTRA, +MFINALFUNC_MODIFY, and +MINITCOND +parameters\&. Except for +MINVFUNC, these parameters work like the corresponding simple\-aggregate parameters without +M; they define a separate implementation of the aggregate that includes an inverse transition function\&. +.PP +The syntax with +ORDER BY +in the parameter list creates a special type of aggregate called an +ordered\-set aggregate; or if +HYPOTHETICAL +is specified, then a +hypothetical\-set aggregate +is created\&. These aggregates operate over groups of sorted values in order\-dependent ways, so that specification of an input sort order is an essential part of a call\&. Also, they can have +direct +arguments, which are arguments that are evaluated only once per aggregation rather than once per input row\&. Hypothetical\-set aggregates are a subclass of ordered\-set aggregates in which some of the direct arguments are required to match, in number and data types, the aggregated argument columns\&. This allows the values of those direct arguments to be added to the collection of aggregate\-input rows as an additional +\(lqhypothetical\(rq +row\&. +.PP +An aggregate can optionally support +partial aggregation, as described in +Section\ \&38.12.4\&. This requires specifying the +COMBINEFUNC +parameter\&. If the +\fIstate_data_type\fR +is +internal, it\*(Aqs usually also appropriate to provide the +SERIALFUNC +and +DESERIALFUNC +parameters so that parallel aggregation is possible\&. Note that the aggregate must also be marked +PARALLEL SAFE +to enable parallel aggregation\&. +.PP +Aggregates that behave like +\fBMIN\fR +or +\fBMAX\fR +can sometimes be optimized by looking into an index instead of scanning every input row\&. If this aggregate can be so optimized, indicate it by specifying a +sort operator\&. The basic requirement is that the aggregate must yield the first element in the sort ordering induced by the operator; in other words: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT agg(col) FROM tab; +.fi +.if n \{\ +.RE +.\} +.sp +must be equivalent to: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; +.fi +.if n \{\ +.RE +.\} +.sp +Further assumptions are that the aggregate ignores null inputs, and that it delivers a null result if and only if there were no non\-null inputs\&. Ordinarily, a data type\*(Aqs +< +operator is the proper sort operator for +\fBMIN\fR, and +> +is the proper sort operator for +\fBMAX\fR\&. Note that the optimization will never actually take effect unless the specified operator is the +\(lqless than\(rq +or +\(lqgreater than\(rq +strategy member of a B\-tree index operator class\&. +.PP +To be able to create an aggregate function, you must have +USAGE +privilege on the argument types, the state type(s), and the return type, as well as +EXECUTE +privilege on the supporting functions\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the aggregate function to create\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN +or +VARIADIC\&. (Aggregate functions do not support +OUT +arguments\&.) If omitted, the default is +IN\&. Only the last argument can be marked +VARIADIC\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. This is currently only useful for documentation purposes\&. If omitted, the argument has no name\&. +.RE +.PP +\fIarg_data_type\fR +.RS 4 +An input data type on which this aggregate function operates\&. To create a zero\-argument aggregate function, write +* +in place of the list of argument specifications\&. (An example of such an aggregate is +\fBcount(*)\fR\&.) +.RE +.PP +\fIbase_type\fR +.RS 4 +In the old syntax for +\fBCREATE AGGREGATE\fR, the input data type is specified by a +basetype +parameter rather than being written next to the aggregate name\&. Note that this syntax allows only one input parameter\&. To define a zero\-argument aggregate function with this syntax, specify the +basetype +as +"ANY" +(not +*)\&. Ordered\-set aggregates cannot be defined with the old syntax\&. +.RE +.PP +\fIsfunc\fR +.RS 4 +The name of the state transition function to be called for each input row\&. For a normal +\fIN\fR\-argument aggregate function, the +\fIsfunc\fR +must take +\fIN\fR+1 arguments, the first being of type +\fIstate_data_type\fR +and the rest matching the declared input data type(s) of the aggregate\&. The function must return a value of type +\fIstate_data_type\fR\&. This function takes the current state value and the current input data value(s), and returns the next state value\&. +.sp +For ordered\-set (including hypothetical\-set) aggregates, the state transition function receives only the current state value and the aggregated arguments, not the direct arguments\&. Otherwise it is the same\&. +.RE +.PP +\fIstate_data_type\fR +.RS 4 +The data type for the aggregate\*(Aqs state value\&. +.RE +.PP +\fIstate_data_size\fR +.RS 4 +The approximate average size (in bytes) of the aggregate\*(Aqs state value\&. If this parameter is omitted or is zero, a default estimate is used based on the +\fIstate_data_type\fR\&. The planner uses this value to estimate the memory required for a grouped aggregate query\&. +.RE +.PP +\fIffunc\fR +.RS 4 +The name of the final function called to compute the aggregate\*(Aqs result after all input rows have been traversed\&. For a normal aggregate, this function must take a single argument of type +\fIstate_data_type\fR\&. The return data type of the aggregate is defined as the return type of this function\&. If +\fIffunc\fR +is not specified, then the ending state value is used as the aggregate\*(Aqs result, and the return type is +\fIstate_data_type\fR\&. +.sp +For ordered\-set (including hypothetical\-set) aggregates, the final function receives not only the final state value, but also the values of all the direct arguments\&. +.sp +If +FINALFUNC_EXTRA +is specified, then in addition to the final state value and any direct arguments, the final function receives extra NULL values corresponding to the aggregate\*(Aqs regular (aggregated) arguments\&. This is mainly useful to allow correct resolution of the aggregate result type when a polymorphic aggregate is being defined\&. +.RE +.PP +FINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } +.RS 4 +This option specifies whether the final function is a pure function that does not modify its arguments\&. +READ_ONLY +indicates it does not; the other two values indicate that it may change the transition state value\&. See +Notes +below for more detail\&. The default is +READ_ONLY, except for ordered\-set aggregates, for which the default is +READ_WRITE\&. +.RE +.PP +\fIcombinefunc\fR +.RS 4 +The +\fIcombinefunc\fR +function may optionally be specified to allow the aggregate function to support partial aggregation\&. If provided, the +\fIcombinefunc\fR +must combine two +\fIstate_data_type\fR +values, each containing the result of aggregation over some subset of the input values, to produce a new +\fIstate_data_type\fR +that represents the result of aggregating over both sets of inputs\&. This function can be thought of as an +\fIsfunc\fR, where instead of acting upon an individual input row and adding it to the running aggregate state, it adds another aggregate state to the running state\&. +.sp +The +\fIcombinefunc\fR +must be declared as taking two arguments of the +\fIstate_data_type\fR +and returning a value of the +\fIstate_data_type\fR\&. Optionally this function may be +\(lqstrict\(rq\&. In this case the function will not be called when either of the input states are null; the other state will be taken as the correct result\&. +.sp +For aggregate functions whose +\fIstate_data_type\fR +is +internal, the +\fIcombinefunc\fR +must not be strict\&. In this case the +\fIcombinefunc\fR +must ensure that null states are handled correctly and that the state being returned is properly stored in the aggregate memory context\&. +.RE +.PP +\fIserialfunc\fR +.RS 4 +An aggregate function whose +\fIstate_data_type\fR +is +internal +can participate in parallel aggregation only if it has a +\fIserialfunc\fR +function, which must serialize the aggregate state into a +bytea +value for transmission to another process\&. This function must take a single argument of type +internal +and return type +bytea\&. A corresponding +\fIdeserialfunc\fR +is also required\&. +.RE +.PP +\fIdeserialfunc\fR +.RS 4 +Deserialize a previously serialized aggregate state back into +\fIstate_data_type\fR\&. This function must take two arguments of types +bytea +and +internal, and produce a result of type +internal\&. (Note: the second, +internal +argument is unused, but is required for type safety reasons\&.) +.RE +.PP +\fIinitial_condition\fR +.RS 4 +The initial setting for the state value\&. This must be a string constant in the form accepted for the data type +\fIstate_data_type\fR\&. If not specified, the state value starts out null\&. +.RE +.PP +\fImsfunc\fR +.RS 4 +The name of the forward state transition function to be called for each input row in moving\-aggregate mode\&. This is exactly like the regular transition function, except that its first argument and result are of type +\fImstate_data_type\fR, which might be different from +\fIstate_data_type\fR\&. +.RE +.PP +\fIminvfunc\fR +.RS 4 +The name of the inverse state transition function to be used in moving\-aggregate mode\&. This function has the same argument and result types as +\fImsfunc\fR, but it is used to remove a value from the current aggregate state, rather than add a value to it\&. The inverse transition function must have the same strictness attribute as the forward state transition function\&. +.RE +.PP +\fImstate_data_type\fR +.RS 4 +The data type for the aggregate\*(Aqs state value, when using moving\-aggregate mode\&. +.RE +.PP +\fImstate_data_size\fR +.RS 4 +The approximate average size (in bytes) of the aggregate\*(Aqs state value, when using moving\-aggregate mode\&. This works the same as +\fIstate_data_size\fR\&. +.RE +.PP +\fImffunc\fR +.RS 4 +The name of the final function called to compute the aggregate\*(Aqs result after all input rows have been traversed, when using moving\-aggregate mode\&. This works the same as +\fIffunc\fR, except that its first argument\*(Aqs type is +\fImstate_data_type\fR +and extra dummy arguments are specified by writing +MFINALFUNC_EXTRA\&. The aggregate result type determined by +\fImffunc\fR +or +\fImstate_data_type\fR +must match that determined by the aggregate\*(Aqs regular implementation\&. +.RE +.PP +MFINALFUNC_MODIFY = { READ_ONLY | SHAREABLE | READ_WRITE } +.RS 4 +This option is like +FINALFUNC_MODIFY, but it describes the behavior of the moving\-aggregate final function\&. +.RE +.PP +\fIminitial_condition\fR +.RS 4 +The initial setting for the state value, when using moving\-aggregate mode\&. This works the same as +\fIinitial_condition\fR\&. +.RE +.PP +\fIsort_operator\fR +.RS 4 +The associated sort operator for a +\fBMIN\fR\- or +\fBMAX\fR\-like aggregate\&. This is just an operator name (possibly schema\-qualified)\&. The operator is assumed to have the same input data types as the aggregate (which must be a single\-argument normal aggregate)\&. +.RE +.PP +PARALLEL = { SAFE | RESTRICTED | UNSAFE } +.RS 4 +The meanings of +PARALLEL SAFE, +PARALLEL RESTRICTED, and +PARALLEL UNSAFE +are the same as in +\fBCREATE FUNCTION\fR\&. An aggregate will not be considered for parallelization if it is marked +PARALLEL UNSAFE +(which is the default!) or +PARALLEL RESTRICTED\&. Note that the parallel\-safety markings of the aggregate\*(Aqs support functions are not consulted by the planner, only the marking of the aggregate itself\&. +.RE +.PP +HYPOTHETICAL +.RS 4 +For ordered\-set aggregates only, this flag specifies that the aggregate arguments are to be processed according to the requirements for hypothetical\-set aggregates: that is, the last few direct arguments must match the data types of the aggregated (WITHIN GROUP) arguments\&. The +HYPOTHETICAL +flag has no effect on run\-time behavior, only on parse\-time resolution of the data types and collations of the aggregate\*(Aqs arguments\&. +.RE +.PP +The parameters of +\fBCREATE AGGREGATE\fR +can be written in any order, not just the order illustrated above\&. +.SH "NOTES" +.PP +In parameters that specify support function names, you can write a schema name if needed, for example +SFUNC = public\&.sum\&. Do not write argument types there, however \(em the argument types of the support functions are determined from other parameters\&. +.PP +Ordinarily, PostgreSQL functions are expected to be true functions that do not modify their input values\&. However, an aggregate transition function, +\fIwhen used in the context of an aggregate\fR, is allowed to cheat and modify its transition\-state argument in place\&. This can provide substantial performance benefits compared to making a fresh copy of the transition state each time\&. +.PP +Likewise, while an aggregate final function is normally expected not to modify its input values, sometimes it is impractical to avoid modifying the transition\-state argument\&. Such behavior must be declared using the +FINALFUNC_MODIFY +parameter\&. The +READ_WRITE +value indicates that the final function modifies the transition state in unspecified ways\&. This value prevents use of the aggregate as a window function, and it also prevents merging of transition states for aggregate calls that share the same input values and transition functions\&. The +SHAREABLE +value indicates that the transition function cannot be applied after the final function, but multiple final\-function calls can be performed on the ending transition state value\&. This value prevents use of the aggregate as a window function, but it allows merging of transition states\&. (That is, the optimization of interest here is not applying the same final function repeatedly, but applying different final functions to the same ending transition state value\&. This is allowed as long as none of the final functions are marked +READ_WRITE\&.) +.PP +If an aggregate supports moving\-aggregate mode, it will improve calculation efficiency when the aggregate is used as a window function for a window with moving frame start (that is, a frame start mode other than +UNBOUNDED PRECEDING)\&. Conceptually, the forward transition function adds input values to the aggregate\*(Aqs state when they enter the window frame from the bottom, and the inverse transition function removes them again when they leave the frame at the top\&. So, when values are removed, they are always removed in the same order they were added\&. Whenever the inverse transition function is invoked, it will thus receive the earliest added but not yet removed argument value(s)\&. The inverse transition function can assume that at least one row will remain in the current state after it removes the oldest row\&. (When this would not be the case, the window function mechanism simply starts a fresh aggregation, rather than using the inverse transition function\&.) +.PP +The forward transition function for moving\-aggregate mode is not allowed to return NULL as the new state value\&. If the inverse transition function returns NULL, this is taken as an indication that the inverse function cannot reverse the state calculation for this particular input, and so the aggregate calculation will be redone from scratch for the current frame starting position\&. This convention allows moving\-aggregate mode to be used in situations where there are some infrequent cases that are impractical to reverse out of the running state value\&. +.PP +If no moving\-aggregate implementation is supplied, the aggregate can still be used with moving frames, but +PostgreSQL +will recompute the whole aggregation whenever the start of the frame moves\&. Note that whether or not the aggregate supports moving\-aggregate mode, +PostgreSQL +can handle a moving frame end without recalculation; this is done by continuing to add new values to the aggregate\*(Aqs state\&. This is why use of an aggregate as a window function requires that the final function be read\-only: it must not damage the aggregate\*(Aqs state value, so that the aggregation can be continued even after an aggregate result value has been obtained for one set of frame boundaries\&. +.PP +The syntax for ordered\-set aggregates allows +VARIADIC +to be specified for both the last direct parameter and the last aggregated (WITHIN GROUP) parameter\&. However, the current implementation restricts use of +VARIADIC +in two ways\&. First, ordered\-set aggregates can only use +VARIADIC "any", not other variadic array types\&. Second, if the last direct parameter is +VARIADIC "any", then there can be only one aggregated parameter and it must also be +VARIADIC "any"\&. (In the representation used in the system catalogs, these two parameters are merged into a single +VARIADIC "any" +item, since +pg_proc +cannot represent functions with more than one +VARIADIC +parameter\&.) If the aggregate is a hypothetical\-set aggregate, the direct arguments that match the +VARIADIC "any" +parameter are the hypothetical ones; any preceding parameters represent additional direct arguments that are not constrained to match the aggregated arguments\&. +.PP +Currently, ordered\-set aggregates do not need to support moving\-aggregate mode, since they cannot be used as window functions\&. +.PP +Partial (including parallel) aggregation is currently not supported for ordered\-set aggregates\&. Also, it will never be used for aggregate calls that include +DISTINCT +or +ORDER BY +clauses, since those semantics cannot be supported during partial aggregation\&. +.SH "EXAMPLES" +.PP +See +Section\ \&38.12\&. +.SH "COMPATIBILITY" +.PP +\fBCREATE AGGREGATE\fR +is a +PostgreSQL +language extension\&. The SQL standard does not provide for user\-defined aggregate functions\&. +.SH "SEE ALSO" +ALTER AGGREGATE (\fBALTER_AGGREGATE\fR(7)), DROP AGGREGATE (\fBDROP_AGGREGATE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_CAST.7 b/doc/src/sgml/man7/CREATE_CAST.7 new file mode 100644 index 0000000..0b56d65 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_CAST.7 @@ -0,0 +1,373 @@ +'\" t +.\" Title: CREATE CAST +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE CAST" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_CAST \- define a new cast +.SH "SYNOPSIS" +.sp +.nf +CREATE CAST (\fIsource_type\fR AS \fItarget_type\fR) + WITH FUNCTION \fIfunction_name\fR [ (\fIargument_type\fR [, \&.\&.\&.]) ] + [ AS ASSIGNMENT | AS IMPLICIT ] + +CREATE CAST (\fIsource_type\fR AS \fItarget_type\fR) + WITHOUT FUNCTION + [ AS ASSIGNMENT | AS IMPLICIT ] + +CREATE CAST (\fIsource_type\fR AS \fItarget_type\fR) + WITH INOUT + [ AS ASSIGNMENT | AS IMPLICIT ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE CAST\fR +defines a new cast\&. A cast specifies how to perform a conversion between two data types\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT CAST(42 AS float8); +.fi +.if n \{\ +.RE +.\} +.sp +converts the integer constant 42 to type +float8 +by invoking a previously specified function, in this case +float8(int4)\&. (If no suitable cast has been defined, the conversion fails\&.) +.PP +Two types can be +binary coercible, which means that the conversion can be performed +\(lqfor free\(rq +without invoking any function\&. This requires that corresponding values use the same internal representation\&. For instance, the types +text +and +varchar +are binary coercible both ways\&. Binary coercibility is not necessarily a symmetric relationship\&. For example, the cast from +xml +to +text +can be performed for free in the present implementation, but the reverse direction requires a function that performs at least a syntax check\&. (Two types that are binary coercible both ways are also referred to as binary compatible\&.) +.PP +You can define a cast as an +I/O conversion cast +by using the +WITH INOUT +syntax\&. An I/O conversion cast is performed by invoking the output function of the source data type, and passing the resulting string to the input function of the target data type\&. In many common cases, this feature avoids the need to write a separate cast function for conversion\&. An I/O conversion cast acts the same as a regular function\-based cast; only the implementation is different\&. +.PP +By default, a cast can be invoked only by an explicit cast request, that is an explicit +CAST(\fIx\fR AS \fItypename\fR) +or +\fIx\fR::\fItypename\fR +construct\&. +.PP +If the cast is marked +AS ASSIGNMENT +then it can be invoked implicitly when assigning a value to a column of the target data type\&. For example, supposing that +foo\&.f1 +is a column of type +text, then: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO foo (f1) VALUES (42); +.fi +.if n \{\ +.RE +.\} +.sp +will be allowed if the cast from type +integer +to type +text +is marked +AS ASSIGNMENT, otherwise not\&. (We generally use the term +assignment cast +to describe this kind of cast\&.) +.PP +If the cast is marked +AS IMPLICIT +then it can be invoked implicitly in any context, whether assignment or internally in an expression\&. (We generally use the term +implicit cast +to describe this kind of cast\&.) For example, consider this query: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT 2 + 4\&.0; +.fi +.if n \{\ +.RE +.\} +.sp +The parser initially marks the constants as being of type +integer +and +numeric +respectively\&. There is no +integer ++ +numeric +operator in the system catalogs, but there is a +numeric ++ +numeric +operator\&. The query will therefore succeed if a cast from +integer +to +numeric +is available and is marked +AS IMPLICIT +\(em which in fact it is\&. The parser will apply the implicit cast and resolve the query as if it had been written +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT CAST ( 2 AS numeric ) + 4\&.0; +.fi +.if n \{\ +.RE +.\} +.PP +Now, the catalogs also provide a cast from +numeric +to +integer\&. If that cast were marked +AS IMPLICIT +\(em which it is not \(em then the parser would be faced with choosing between the above interpretation and the alternative of casting the +numeric +constant to +integer +and applying the +integer ++ +integer +operator\&. Lacking any knowledge of which choice to prefer, it would give up and declare the query ambiguous\&. The fact that only one of the two casts is implicit is the way in which we teach the parser to prefer resolution of a mixed +numeric\-and\-integer +expression as +numeric; there is no built\-in knowledge about that\&. +.PP +It is wise to be conservative about marking casts as implicit\&. An overabundance of implicit casting paths can cause +PostgreSQL +to choose surprising interpretations of commands, or to be unable to resolve commands at all because there are multiple possible interpretations\&. A good rule of thumb is to make a cast implicitly invokable only for information\-preserving transformations between types in the same general type category\&. For example, the cast from +int2 +to +int4 +can reasonably be implicit, but the cast from +float8 +to +int4 +should probably be assignment\-only\&. Cross\-type\-category casts, such as +text +to +int4, are best made explicit\-only\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +Sometimes it is necessary for usability or standards\-compliance reasons to provide multiple implicit casts among a set of types, resulting in ambiguity that cannot be avoided as above\&. The parser has a fallback heuristic based on +type categories +and +preferred types +that can help to provide desired behavior in such cases\&. See +CREATE TYPE (\fBCREATE_TYPE\fR(7)) +for more information\&. +.sp .5v +.RE +.PP +To be able to create a cast, you must own the source or the target data type and have +USAGE +privilege on the other type\&. To create a binary\-coercible cast, you must be superuser\&. (This restriction is made because an erroneous binary\-coercible cast conversion can easily crash the server\&.) +.SH "PARAMETERS" +.PP +\fIsource_type\fR +.RS 4 +The name of the source data type of the cast\&. +.RE +.PP +\fItarget_type\fR +.RS 4 +The name of the target data type of the cast\&. +.RE +.PP +\fIfunction_name\fR[(\fIargument_type\fR [, \&.\&.\&.])] +.RS 4 +The function used to perform the cast\&. The function name can be schema\-qualified\&. If it is not, the function will be looked up in the schema search path\&. The function\*(Aqs result data type must match the target type of the cast\&. Its arguments are discussed below\&. If no argument list is specified, the function name must be unique in its schema\&. +.RE +.PP +WITHOUT FUNCTION +.RS 4 +Indicates that the source type is binary\-coercible to the target type, so no function is required to perform the cast\&. +.RE +.PP +WITH INOUT +.RS 4 +Indicates that the cast is an I/O conversion cast, performed by invoking the output function of the source data type, and passing the resulting string to the input function of the target data type\&. +.RE +.PP +AS ASSIGNMENT +.RS 4 +Indicates that the cast can be invoked implicitly in assignment contexts\&. +.RE +.PP +AS IMPLICIT +.RS 4 +Indicates that the cast can be invoked implicitly in any context\&. +.RE +.PP +Cast implementation functions can have one to three arguments\&. The first argument type must be identical to or binary\-coercible from the cast\*(Aqs source type\&. The second argument, if present, must be type +integer; it receives the type modifier associated with the destination type, or +\-1 +if there is none\&. The third argument, if present, must be type +boolean; it receives +true +if the cast is an explicit cast, +false +otherwise\&. (Bizarrely, the SQL standard demands different behaviors for explicit and implicit casts in some cases\&. This argument is supplied for functions that must implement such casts\&. It is not recommended that you design your own data types so that this matters\&.) +.PP +The return type of a cast function must be identical to or binary\-coercible to the cast\*(Aqs target type\&. +.PP +Ordinarily a cast must have different source and target data types\&. However, it is allowed to declare a cast with identical source and target types if it has a cast implementation function with more than one argument\&. This is used to represent type\-specific length coercion functions in the system catalogs\&. The named function is used to coerce a value of the type to the type modifier value given by its second argument\&. +.PP +When a cast has different source and target types and a function that takes more than one argument, it supports converting from one type to another and applying a length coercion in a single step\&. When no such entry is available, coercion to a type that uses a type modifier involves two cast steps, one to convert between data types and a second to apply the modifier\&. +.PP +A cast to or from a domain type currently has no effect\&. Casting to or from a domain uses the casts associated with its underlying type\&. +.SH "NOTES" +.PP +Use +\fBDROP CAST\fR +to remove user\-defined casts\&. +.PP +Remember that if you want to be able to convert types both ways you need to declare casts both ways explicitly\&. +.PP +It is normally not necessary to create casts between user\-defined types and the standard string types (text, +varchar, and +char(\fIn\fR), as well as user\-defined types that are defined to be in the string category)\&. +PostgreSQL +provides automatic I/O conversion casts for that\&. The automatic casts to string types are treated as assignment casts, while the automatic casts from string types are explicit\-only\&. You can override this behavior by declaring your own cast to replace an automatic cast, but usually the only reason to do so is if you want the conversion to be more easily invokable than the standard assignment\-only or explicit\-only setting\&. Another possible reason is that you want the conversion to behave differently from the type\*(Aqs I/O function; but that is sufficiently surprising that you should think twice about whether it\*(Aqs a good idea\&. (A small number of the built\-in types do indeed have different behaviors for conversions, mostly because of requirements of the SQL standard\&.) +.PP +While not required, it is recommended that you continue to follow this old convention of naming cast implementation functions after the target data type\&. Many users are used to being able to cast data types using a function\-style notation, that is +\fItypename\fR(\fIx\fR)\&. This notation is in fact nothing more nor less than a call of the cast implementation function; it is not specially treated as a cast\&. If your conversion functions are not named to support this convention then you will have surprised users\&. Since +PostgreSQL +allows overloading of the same function name with different argument types, there is no difficulty in having multiple conversion functions from different types that all use the target type\*(Aqs name\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +Actually the preceding paragraph is an oversimplification: there are two cases in which a function\-call construct will be treated as a cast request without having matched it to an actual function\&. If a function call +\fIname\fR(\fIx\fR) does not exactly match any existing function, but +\fIname\fR +is the name of a data type and +pg_cast +provides a binary\-coercible cast to this type from the type of +\fIx\fR, then the call will be construed as a binary\-coercible cast\&. This exception is made so that binary\-coercible casts can be invoked using functional syntax, even though they lack any function\&. Likewise, if there is no +pg_cast +entry but the cast would be to or from a string type, the call will be construed as an I/O conversion cast\&. This exception allows I/O conversion casts to be invoked using functional syntax\&. +.sp .5v +.RE +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +There is also an exception to the exception: I/O conversion casts from composite types to string types cannot be invoked using functional syntax, but must be written in explicit cast syntax (either +CAST +or +:: +notation)\&. This exception was added because after the introduction of automatically\-provided I/O conversion casts, it was found too easy to accidentally invoke such a cast when a function or column reference was intended\&. +.sp .5v +.RE +.SH "EXAMPLES" +.PP +To create an assignment cast from type +bigint +to type +int4 +using the function +int4(bigint): +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint) AS ASSIGNMENT; +.fi +.if n \{\ +.RE +.\} +.sp +(This cast is already predefined in the system\&.) +.SH "COMPATIBILITY" +.PP +The +\fBCREATE CAST\fR +command conforms to the +SQL +standard, except that SQL does not make provisions for binary\-coercible types or extra arguments to implementation functions\&. +AS IMPLICIT +is a +PostgreSQL +extension, too\&. +.SH "SEE ALSO" +.PP +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), +CREATE TYPE (\fBCREATE_TYPE\fR(7)), +DROP CAST (\fBDROP_CAST\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_COLLATION.7 b/doc/src/sgml/man7/CREATE_COLLATION.7 new file mode 100644 index 0000000..8d518ba --- /dev/null +++ b/doc/src/sgml/man7/CREATE_COLLATION.7 @@ -0,0 +1,197 @@ +'\" t +.\" Title: CREATE COLLATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE COLLATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_COLLATION \- define a new collation +.SH "SYNOPSIS" +.sp +.nf +CREATE COLLATION [ IF NOT EXISTS ] \fIname\fR ( + [ LOCALE = \fIlocale\fR, ] + [ LC_COLLATE = \fIlc_collate\fR, ] + [ LC_CTYPE = \fIlc_ctype\fR, ] + [ PROVIDER = \fIprovider\fR, ] + [ DETERMINISTIC = \fIboolean\fR, ] + [ VERSION = \fIversion\fR ] +) +CREATE COLLATION [ IF NOT EXISTS ] \fIname\fR FROM \fIexisting_collation\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE COLLATION\fR +defines a new collation using the specified operating system locale settings, or by copying an existing collation\&. +.PP +To be able to create a collation, you must have +CREATE +privilege on the destination schema\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a collation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing collation is anything like the one that would have been created\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the collation\&. The collation name can be schema\-qualified\&. If it is not, the collation is defined in the current schema\&. The collation name must be unique within that schema\&. (The system catalogs can contain collations with the same name for other encodings, but these are ignored if the database encoding does not match\&.) +.RE +.PP +\fIlocale\fR +.RS 4 +This is a shortcut for setting +LC_COLLATE +and +LC_CTYPE +at once\&. If you specify this, you cannot specify either of those parameters\&. +.RE +.PP +\fIlc_collate\fR +.RS 4 +Use the specified operating system locale for the +LC_COLLATE +locale category\&. +.RE +.PP +\fIlc_ctype\fR +.RS 4 +Use the specified operating system locale for the +LC_CTYPE +locale category\&. +.RE +.PP +\fIprovider\fR +.RS 4 +Specifies the provider to use for locale services associated with this collation\&. Possible values are: +icu, +libc\&. +libc +is the default\&. The available choices depend on the operating system and build options\&. +.RE +.PP +DETERMINISTIC +.RS 4 +Specifies whether the collation should use deterministic comparisons\&. The default is true\&. A deterministic comparison considers strings that are not byte\-wise equal to be unequal even if they are considered logically equal by the comparison\&. PostgreSQL breaks ties using a byte\-wise comparison\&. Comparison that is not deterministic can make the collation be, say, case\- or accent\-insensitive\&. For that, you need to choose an appropriate +LC_COLLATE +setting +\fIand\fR +set the collation to not deterministic here\&. +.sp +Nondeterministic collations are only supported with the ICU provider\&. +.RE +.PP +\fIversion\fR +.RS 4 +Specifies the version string to store with the collation\&. Normally, this should be omitted, which will cause the version to be computed from the actual version of the collation as provided by the operating system\&. This option is intended to be used by +\fBpg_upgrade\fR +for copying the version from an existing installation\&. +.sp +See also +ALTER COLLATION (\fBALTER_COLLATION\fR(7)) +for how to handle collation version mismatches\&. +.RE +.PP +\fIexisting_collation\fR +.RS 4 +The name of an existing collation to copy\&. The new collation will have the same properties as the existing one, but it will be an independent object\&. +.RE +.SH "NOTES" +.PP +\fBCREATE COLLATION\fR +takes a +SHARE ROW EXCLUSIVE +lock, which is self\-conflicting, on the +pg_collation +system catalog, so only one +\fBCREATE COLLATION\fR +command can run at a time\&. +.PP +Use +\fBDROP COLLATION\fR +to remove user\-defined collations\&. +.PP +See +Section\ \&24.2.2.3 +for more information on how to create collations\&. +.PP +When using the +libc +collation provider, the locale must be applicable to the current database encoding\&. See +CREATE DATABASE (\fBCREATE_DATABASE\fR(7)) +for the precise rules\&. +.SH "EXAMPLES" +.PP +To create a collation from the operating system locale +fr_FR\&.utf8 +(assuming the current database encoding is +UTF8): +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE COLLATION french (locale = \*(Aqfr_FR\&.utf8\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +To create a collation using the ICU provider using German phone book sort order: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE COLLATION german_phonebook (provider = icu, locale = \*(Aqde\-u\-co\-phonebk\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +To create a collation from an existing collation: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE COLLATION german FROM "de_DE"; +.fi +.if n \{\ +.RE +.\} +.sp +This can be convenient to be able to use operating\-system\-independent collation names in applications\&. +.SH "COMPATIBILITY" +.PP +There is a +\fBCREATE COLLATION\fR +statement in the SQL standard, but it is limited to copying an existing collation\&. The syntax to create a new collation is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER COLLATION (\fBALTER_COLLATION\fR(7)), DROP COLLATION (\fBDROP_COLLATION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_CONVERSION.7 b/doc/src/sgml/man7/CREATE_CONVERSION.7 new file mode 100644 index 0000000..834af46 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_CONVERSION.7 @@ -0,0 +1,145 @@ +'\" t +.\" Title: CREATE CONVERSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE CONVERSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_CONVERSION \- define a new encoding conversion +.SH "SYNOPSIS" +.sp +.nf +CREATE [ DEFAULT ] CONVERSION \fIname\fR + FOR \fIsource_encoding\fR TO \fIdest_encoding\fR FROM \fIfunction_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE CONVERSION\fR +defines a new conversion between two character set encodings\&. +.PP +Conversions that are marked +DEFAULT +can be used for automatic encoding conversion between client and server\&. To support that usage, two conversions, from encoding A to B +\fIand\fR +from encoding B to A, must be defined\&. +.PP +To be able to create a conversion, you must have +EXECUTE +privilege on the function and +CREATE +privilege on the destination schema\&. +.SH "PARAMETERS" +.PP +DEFAULT +.RS 4 +The +DEFAULT +clause indicates that this conversion is the default for this particular source to destination encoding\&. There should be only one default encoding in a schema for the encoding pair\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the conversion\&. The conversion name can be schema\-qualified\&. If it is not, the conversion is defined in the current schema\&. The conversion name must be unique within a schema\&. +.RE +.PP +\fIsource_encoding\fR +.RS 4 +The source encoding name\&. +.RE +.PP +\fIdest_encoding\fR +.RS 4 +The destination encoding name\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +The function used to perform the conversion\&. The function name can be schema\-qualified\&. If it is not, the function will be looked up in the path\&. +.sp +The function must have the following signature: +.sp +.if n \{\ +.RS 4 +.\} +.nf +conv_proc( + integer, \-\- source encoding ID + integer, \-\- destination encoding ID + cstring, \-\- source string (null terminated C string) + internal, \-\- destination (fill with a null terminated C string) + integer, \-\- source string length + boolean \-\- if true, don\*(Aqt throw an error if conversion fails +) RETURNS integer; +.fi +.if n \{\ +.RE +.\} +.sp +The return value is the number of source bytes that were successfully converted\&. If the last argument is false, the function must throw an error on invalid input, and the return value is always equal to the source string length\&. +.RE +.SH "NOTES" +.PP +Neither the source nor the destination encoding can be +SQL_ASCII, as the server\*(Aqs behavior for cases involving the +SQL_ASCII +\(lqencoding\(rq +is hard\-wired\&. +.PP +Use +\fBDROP CONVERSION\fR +to remove user\-defined conversions\&. +.PP +The privileges required to create a conversion might be changed in a future release\&. +.SH "EXAMPLES" +.PP +To create a conversion from encoding +UTF8 +to +LATIN1 +using +\fBmyfunc\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE CONVERSION myconv FOR \*(AqUTF8\*(Aq TO \*(AqLATIN1\*(Aq FROM myfunc; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE CONVERSION\fR +is a +PostgreSQL +extension\&. There is no +\fBCREATE CONVERSION\fR +statement in the SQL standard, but a +\fBCREATE TRANSLATION\fR +statement that is very similar in purpose and syntax\&. +.SH "SEE ALSO" +ALTER CONVERSION (\fBALTER_CONVERSION\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP CONVERSION (\fBDROP_CONVERSION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_DATABASE.7 b/doc/src/sgml/man7/CREATE_DATABASE.7 new file mode 100644 index 0000000..c1cb4e9 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_DATABASE.7 @@ -0,0 +1,353 @@ +'\" t +.\" Title: CREATE DATABASE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE DATABASE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_DATABASE \- create a new database +.SH "SYNOPSIS" +.sp +.nf +CREATE DATABASE \fIname\fR + [ WITH ] [ OWNER [=] \fIuser_name\fR ] + [ TEMPLATE [=] \fItemplate\fR ] + [ ENCODING [=] \fIencoding\fR ] + [ STRATEGY [=] \fIstrategy\fR ] ] + [ LOCALE [=] \fIlocale\fR ] + [ LC_COLLATE [=] \fIlc_collate\fR ] + [ LC_CTYPE [=] \fIlc_ctype\fR ] + [ ICU_LOCALE [=] \fIicu_locale\fR ] + [ LOCALE_PROVIDER [=] \fIlocale_provider\fR ] + [ COLLATION_VERSION = \fIcollation_version\fR ] + [ TABLESPACE [=] \fItablespace_name\fR ] + [ ALLOW_CONNECTIONS [=] \fIallowconn\fR ] + [ CONNECTION LIMIT [=] \fIconnlimit\fR ] + [ IS_TEMPLATE [=] \fIistemplate\fR ] + [ OID [=] \fIoid\fR ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE DATABASE\fR +creates a new +PostgreSQL +database\&. +.PP +To create a database, you must be a superuser or have the special +CREATEDB +privilege\&. See +CREATE ROLE (\fBCREATE_ROLE\fR(7))\&. +.PP +By default, the new database will be created by cloning the standard system database +template1\&. A different template can be specified by writing +TEMPLATE \fIname\fR\&. In particular, by writing +TEMPLATE template0, you can create a pristine database (one where no user\-defined objects exist and where the system objects have not been altered) containing only the standard objects predefined by your version of +PostgreSQL\&. This is useful if you wish to avoid copying any installation\-local objects that might have been added to +template1\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of a database to create\&. +.RE +.PP +\fIuser_name\fR +.RS 4 +The role name of the user who will own the new database, or +DEFAULT +to use the default (namely, the user executing the command)\&. To create a database owned by another role, you must be a direct or indirect member of that role, or be a superuser\&. +.RE +.PP +\fItemplate\fR +.RS 4 +The name of the template from which to create the new database, or +DEFAULT +to use the default template (template1)\&. +.RE +.PP +\fIencoding\fR +.RS 4 +Character set encoding to use in the new database\&. Specify a string constant (e\&.g\&., +\*(AqSQL_ASCII\*(Aq), or an integer encoding number, or +DEFAULT +to use the default encoding (namely, the encoding of the template database)\&. The character sets supported by the +PostgreSQL +server are described in +Section\ \&24.3.1\&. See below for additional restrictions\&. +.RE +.PP +\fIstrategy\fR +.RS 4 +Strategy to be used in creating the new database\&. If the +WAL_LOG +strategy is used, the database will be copied block by block and each block will be separately written to the write\-ahead log\&. This is the most efficient strategy in cases where the template database is small, and therefore it is the default\&. The older +FILE_COPY +strategy is also available\&. This strategy writes a small record to the write\-ahead log for each tablespace used by the target database\&. Each such record represents copying an entire directory to a new location at the filesystem level\&. While this does reduce the write\-ahead log volume substantially, especially if the template database is large, it also forces the system to perform a checkpoint both before and after the creation of the new database\&. In some situations, this may have a noticeable negative impact on overall system performance\&. +.RE +.PP +\fIlocale\fR +.RS 4 +This is a shortcut for setting +LC_COLLATE +and +LC_CTYPE +at once\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +The other locale settings +lc_messages, +lc_monetary, +lc_numeric, and +lc_time +are not fixed per database and are not set by this command\&. If you want to make them the default for a specific database, you can use +ALTER DATABASE \&.\&.\&. SET\&. +.sp .5v +.RE +.RE +.PP +\fIlc_collate\fR +.RS 4 +Collation order (LC_COLLATE) to use in the new database\&. This affects the sort order applied to strings, e\&.g\&., in queries with ORDER BY, as well as the order used in indexes on text columns\&. The default is to use the collation order of the template database\&. See below for additional restrictions\&. +.RE +.PP +\fIlc_ctype\fR +.RS 4 +Character classification (LC_CTYPE) to use in the new database\&. This affects the categorization of characters, e\&.g\&., lower, upper and digit\&. The default is to use the character classification of the template database\&. See below for additional restrictions\&. +.RE +.PP +\fIicu_locale\fR +.RS 4 +Specifies the ICU locale ID if the ICU locale provider is used\&. +.RE +.PP +\fIlocale_provider\fR +.RS 4 +Specifies the provider to use for the default collation in this database\&. Possible values are: +icu, +libc\&. +libc +is the default\&. The available choices depend on the operating system and build options\&. +.RE +.PP +\fIcollation_version\fR +.RS 4 +Specifies the collation version string to store with the database\&. Normally, this should be omitted, which will cause the version to be computed from the actual version of the database collation as provided by the operating system\&. This option is intended to be used by +\fBpg_upgrade\fR +for copying the version from an existing installation\&. +.sp +See also +ALTER DATABASE (\fBALTER_DATABASE\fR(7)) +for how to handle database collation version mismatches\&. +.RE +.PP +\fItablespace_name\fR +.RS 4 +The name of the tablespace that will be associated with the new database, or +DEFAULT +to use the template database\*(Aqs tablespace\&. This tablespace will be the default tablespace used for objects created in this database\&. See +CREATE TABLESPACE (\fBCREATE_TABLESPACE\fR(7)) +for more information\&. +.RE +.PP +\fIallowconn\fR +.RS 4 +If false then no one can connect to this database\&. The default is true, allowing connections (except as restricted by other mechanisms, such as +GRANT/REVOKE CONNECT)\&. +.RE +.PP +\fIconnlimit\fR +.RS 4 +How many concurrent connections can be made to this database\&. \-1 (the default) means no limit\&. +.RE +.PP +\fIistemplate\fR +.RS 4 +If true, then this database can be cloned by any user with +CREATEDB +privileges; if false (the default), then only superusers or the owner of the database can clone it\&. +.RE +.PP +\fIoid\fR +.RS 4 +The object identifier to be used for the new database\&. If this parameter is not specified, +PostgreSQL +will choose a suitable OID automatically\&. This parameter is primarily intended for internal use by +pg_upgrade, and only +pg_upgrade +can specify a value less than 16384\&. +.RE +.PP +Optional parameters can be written in any order, not only the order illustrated above\&. +.SH "NOTES" +.PP +\fBCREATE DATABASE\fR +cannot be executed inside a transaction block\&. +.PP +Errors along the line of +\(lqcould not initialize database directory\(rq +are most likely related to insufficient permissions on the data directory, a full disk, or other file system problems\&. +.PP +Use +\fBDROP DATABASE\fR +to remove a database\&. +.PP +The program +\fBcreatedb\fR(1) +is a wrapper program around this command, provided for convenience\&. +.PP +Database\-level configuration parameters (set via +\fBALTER DATABASE\fR) and database\-level permissions (set via +\fBGRANT\fR) are not copied from the template database\&. +.PP +Although it is possible to copy a database other than +template1 +by specifying its name as the template, this is not (yet) intended as a general\-purpose +\(lq\fBCOPY DATABASE\fR\(rq +facility\&. The principal limitation is that no other sessions can be connected to the template database while it is being copied\&. +\fBCREATE DATABASE\fR +will fail if any other connection exists when it starts; otherwise, new connections to the template database are locked out until +\fBCREATE DATABASE\fR +completes\&. See +Section\ \&23.3 +for more information\&. +.PP +The character set encoding specified for the new database must be compatible with the chosen locale settings (LC_COLLATE +and +LC_CTYPE)\&. If the locale is +C +(or equivalently +POSIX), then all encodings are allowed, but for other locale settings there is only one encoding that will work properly\&. (On Windows, however, UTF\-8 encoding can be used with any locale\&.) +\fBCREATE DATABASE\fR +will allow superusers to specify +SQL_ASCII +encoding regardless of the locale settings, but this choice is deprecated and may result in misbehavior of character\-string functions if data that is not encoding\-compatible with the locale is stored in the database\&. +.PP +The encoding and locale settings must match those of the template database, except when +template0 +is used as template\&. This is because other databases might contain data that does not match the specified encoding, or might contain indexes whose sort ordering is affected by +LC_COLLATE +and +LC_CTYPE\&. Copying such data would result in a database that is corrupt according to the new settings\&. +template0, however, is known to not contain any data or indexes that would be affected\&. +.PP +There is currently no option to use a database locale with nondeterministic comparisons (see +\fBCREATE COLLATION\fR +for an explanation)\&. If this is needed, then per\-column collations would need to be used\&. +.PP +The +CONNECTION LIMIT +option is only enforced approximately; if two new sessions start at about the same time when just one connection +\(lqslot\(rq +remains for the database, it is possible that both will fail\&. Also, the limit is not enforced against superusers or background worker processes\&. +.SH "EXAMPLES" +.PP +To create a new database: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DATABASE lusiadas; +.fi +.if n \{\ +.RE +.\} +.PP +To create a database +sales +owned by user +salesapp +with a default tablespace of +salesspace: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; +.fi +.if n \{\ +.RE +.\} +.PP +To create a database +music +with a different locale: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DATABASE music + LOCALE \*(Aqsv_SE\&.utf8\*(Aq + TEMPLATE template0; +.fi +.if n \{\ +.RE +.\} +.sp +In this example, the +TEMPLATE template0 +clause is required if the specified locale is different from the one in +template1\&. (If it is not, then specifying the locale explicitly is redundant\&.) +.PP +To create a database +music2 +with a different locale and a different character set encoding: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DATABASE music2 + LOCALE \*(Aqsv_SE\&.iso885915\*(Aq + ENCODING LATIN9 + TEMPLATE template0; +.fi +.if n \{\ +.RE +.\} +.sp +The specified locale and encoding settings must match, or an error will be reported\&. +.PP +Note that locale names are specific to the operating system, so that the above commands might not work in the same way everywhere\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE DATABASE\fR +statement in the SQL standard\&. Databases are equivalent to catalogs, whose creation is implementation\-defined\&. +.SH "SEE ALSO" +ALTER DATABASE (\fBALTER_DATABASE\fR(7)), DROP DATABASE (\fBDROP_DATABASE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_DOMAIN.7 b/doc/src/sgml/man7/CREATE_DOMAIN.7 new file mode 100644 index 0000000..d336701 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_DOMAIN.7 @@ -0,0 +1,195 @@ +'\" t +.\" Title: CREATE DOMAIN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE DOMAIN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_DOMAIN \- define a new domain +.SH "SYNOPSIS" +.sp +.nf +CREATE DOMAIN \fIname\fR [ AS ] \fIdata_type\fR + [ COLLATE \fIcollation\fR ] + [ DEFAULT \fIexpression\fR ] + [ \fIconstraint\fR [ \&.\&.\&. ] ] + +where \fIconstraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +{ NOT NULL | NULL | CHECK (\fIexpression\fR) } +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE DOMAIN\fR +creates a new domain\&. A domain is essentially a data type with optional constraints (restrictions on the allowed set of values)\&. The user who defines a domain becomes its owner\&. +.PP +If a schema name is given (for example, +CREATE DOMAIN myschema\&.mydomain \&.\&.\&.) then the domain is created in the specified schema\&. Otherwise it is created in the current schema\&. The domain name must be unique among the types and domains existing in its schema\&. +.PP +Domains are useful for abstracting common constraints on fields into a single location for maintenance\&. For example, several tables might contain email address columns, all requiring the same CHECK constraint to verify the address syntax\&. Define a domain rather than setting up each table\*(Aqs constraint individually\&. +.PP +To be able to create a domain, you must have +USAGE +privilege on the underlying type\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of a domain to be created\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The underlying data type of the domain\&. This can include array specifiers\&. +.RE +.PP +\fIcollation\fR +.RS 4 +An optional collation for the domain\&. If no collation is specified, the domain has the same collation behavior as its underlying data type\&. The underlying type must be collatable if +COLLATE +is specified\&. +.RE +.PP +DEFAULT \fIexpression\fR +.RS 4 +The +DEFAULT +clause specifies a default value for columns of the domain data type\&. The value is any variable\-free expression (but subqueries are not allowed)\&. The data type of the default expression must match the data type of the domain\&. If no default value is specified, then the default value is the null value\&. +.sp +The default expression will be used in any insert operation that does not specify a value for the column\&. If a default value is defined for a particular column, it overrides any default associated with the domain\&. In turn, the domain default overrides any default value associated with the underlying data type\&. +.RE +.PP +CONSTRAINT \fIconstraint_name\fR +.RS 4 +An optional name for a constraint\&. If not specified, the system generates a name\&. +.RE +.PP +NOT NULL +.RS 4 +Values of this domain are prevented from being null (but see notes below)\&. +.RE +.PP +NULL +.RS 4 +Values of this domain are allowed to be null\&. This is the default\&. +.sp +This clause is only intended for compatibility with nonstandard SQL databases\&. Its use is discouraged in new applications\&. +.RE +.PP +CHECK (\fIexpression\fR) +.RS 4 +CHECK +clauses specify integrity constraints or tests which values of the domain must satisfy\&. Each constraint must be an expression producing a Boolean result\&. It should use the key word +VALUE +to refer to the value being tested\&. Expressions evaluating to TRUE or UNKNOWN succeed\&. If the expression produces a FALSE result, an error is reported and the value is not allowed to be converted to the domain type\&. +.sp +Currently, +CHECK +expressions cannot contain subqueries nor refer to variables other than +VALUE\&. +.sp +When a domain has multiple +CHECK +constraints, they will be tested in alphabetical order by name\&. (PostgreSQL +versions before 9\&.5 did not honor any particular firing order for +CHECK +constraints\&.) +.RE +.SH "NOTES" +.PP +Domain constraints, particularly +NOT NULL, are checked when converting a value to the domain type\&. It is possible for a column that is nominally of the domain type to read as null despite there being such a constraint\&. For example, this can happen in an outer\-join query, if the domain column is on the nullable side of the outer join\&. A more subtle example is +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO tab (domcol) VALUES ((SELECT domcol FROM tab WHERE false)); +.fi +.if n \{\ +.RE +.\} +.sp +The empty scalar sub\-SELECT will produce a null value that is considered to be of the domain type, so no further constraint checking is applied to it, and the insertion will succeed\&. +.PP +It is very difficult to avoid such problems, because of SQL\*(Aqs general assumption that a null value is a valid value of every data type\&. Best practice therefore is to design a domain\*(Aqs constraints so that a null value is allowed, and then to apply column +NOT NULL +constraints to columns of the domain type as needed, rather than directly to the domain type\&. +.PP +PostgreSQL +assumes that +CHECK +constraints\*(Aq conditions are immutable, that is, they will always give the same result for the same input value\&. This assumption is what justifies examining +CHECK +constraints only when a value is first converted to be of a domain type, and not at other times\&. (This is essentially the same as the treatment of table +CHECK +constraints, as described in +Section\ \&5.4.1\&.) +.PP +An example of a common way to break this assumption is to reference a user\-defined function in a +CHECK +expression, and then change the behavior of that function\&. +PostgreSQL +does not disallow that, but it will not notice if there are stored values of the domain type that now violate the +CHECK +constraint\&. That would cause a subsequent database dump and restore to fail\&. The recommended way to handle such a change is to drop the constraint (using +\fBALTER DOMAIN\fR), adjust the function definition, and re\-add the constraint, thereby rechecking it against stored data\&. +.SH "EXAMPLES" +.PP +This example creates the +us_postal_code +data type and then uses the type in a table definition\&. A regular expression test is used to verify that the value looks like a valid US postal code: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE DOMAIN us_postal_code AS TEXT +CHECK( + VALUE ~ \*(Aq^\ed{5}$\*(Aq +OR VALUE ~ \*(Aq^\ed{5}\-\ed{4}$\*(Aq +); + +CREATE TABLE us_snail_addy ( + address_id SERIAL PRIMARY KEY, + street1 TEXT NOT NULL, + street2 TEXT, + street3 TEXT, + city TEXT NOT NULL, + postal us_postal_code NOT NULL +); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The command +\fBCREATE DOMAIN\fR +conforms to the SQL standard\&. +.SH "SEE ALSO" +ALTER DOMAIN (\fBALTER_DOMAIN\fR(7)), DROP DOMAIN (\fBDROP_DOMAIN\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_EVENT_TRIGGER.7 b/doc/src/sgml/man7/CREATE_EVENT_TRIGGER.7 new file mode 100644 index 0000000..e1ea71e --- /dev/null +++ b/doc/src/sgml/man7/CREATE_EVENT_TRIGGER.7 @@ -0,0 +1,129 @@ +'\" t +.\" Title: CREATE EVENT TRIGGER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE EVENT TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_EVENT_TRIGGER \- define a new event trigger +.SH "SYNOPSIS" +.sp +.nf +CREATE EVENT TRIGGER \fIname\fR + ON \fIevent\fR + [ WHEN \fIfilter_variable\fR IN (\fIfilter_value\fR [, \&.\&.\&. ]) [ AND \&.\&.\&. ] ] + EXECUTE { FUNCTION | PROCEDURE } \fIfunction_name\fR() +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE EVENT TRIGGER\fR +creates a new event trigger\&. Whenever the designated event occurs and the +WHEN +condition associated with the trigger, if any, is satisfied, the trigger function will be executed\&. For a general introduction to event triggers, see +Chapter\ \&40\&. The user who creates an event trigger becomes its owner\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name to give the new trigger\&. This name must be unique within the database\&. +.RE +.PP +\fIevent\fR +.RS 4 +The name of the event that triggers a call to the given function\&. See +Section\ \&40.1 +for more information on event names\&. +.RE +.PP +\fIfilter_variable\fR +.RS 4 +The name of a variable used to filter events\&. This makes it possible to restrict the firing of the trigger to a subset of the cases in which it is supported\&. Currently the only supported +\fIfilter_variable\fR +is +TAG\&. +.RE +.PP +\fIfilter_value\fR +.RS 4 +A list of values for the associated +\fIfilter_variable\fR +for which the trigger should fire\&. For +TAG, this means a list of command tags (e\&.g\&., +\*(AqDROP FUNCTION\*(Aq)\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +A user\-supplied function that is declared as taking no argument and returning type +event_trigger\&. +.sp +In the syntax of +CREATE EVENT TRIGGER, the keywords +FUNCTION +and +PROCEDURE +are equivalent, but the referenced function must in any case be a function, not a procedure\&. The use of the keyword +PROCEDURE +here is historical and deprecated\&. +.RE +.SH "NOTES" +.PP +Only superusers can create event triggers\&. +.PP +Event triggers are disabled in single\-user mode (see +\fBpostgres\fR(1))\&. If an erroneous event trigger disables the database so much that you can\*(Aqt even drop the trigger, restart in single\-user mode and you\*(Aqll be able to do that\&. +.SH "EXAMPLES" +.PP +Forbid the execution of any +DDL +command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE OR REPLACE FUNCTION abort_any_command() + RETURNS event_trigger + LANGUAGE plpgsql + AS $$ +BEGIN + RAISE EXCEPTION \*(Aqcommand % is disabled\*(Aq, tg_tag; +END; +$$; + +CREATE EVENT TRIGGER abort_ddl ON ddl_command_start + EXECUTE FUNCTION abort_any_command(); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE EVENT TRIGGER\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER EVENT TRIGGER (\fBALTER_EVENT_TRIGGER\fR(7)), DROP EVENT TRIGGER (\fBDROP_EVENT_TRIGGER\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_EXTENSION.7 b/doc/src/sgml/man7/CREATE_EXTENSION.7 new file mode 100644 index 0000000..b3daa80 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_EXTENSION.7 @@ -0,0 +1,188 @@ +'\" t +.\" Title: CREATE EXTENSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE EXTENSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_EXTENSION \- install an extension +.SH "SYNOPSIS" +.sp +.nf +CREATE EXTENSION [ IF NOT EXISTS ] \fIextension_name\fR + [ WITH ] [ SCHEMA \fIschema_name\fR ] + [ VERSION \fIversion\fR ] + [ CASCADE ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE EXTENSION\fR +loads a new extension into the current database\&. There must not be an extension of the same name already loaded\&. +.PP +Loading an extension essentially amounts to running the extension\*(Aqs script file\&. The script will typically create new +SQL +objects such as functions, data types, operators and index support methods\&. +\fBCREATE EXTENSION\fR +additionally records the identities of all the created objects, so that they can be dropped again if +\fBDROP EXTENSION\fR +is issued\&. +.PP +The user who runs +\fBCREATE EXTENSION\fR +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\*(Aqs script\&. +.PP +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 +trusted +in its control file, then it can be installed by any user who has +CREATE +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\*(Aqs 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\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +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\&. +.RE +.PP +\fIextension_name\fR +.RS 4 +The name of the extension to be installed\&. +PostgreSQL +will create the extension using details from the file +SHAREDIR/extension/\fIextension_name\fR\&.control\&. +.RE +.PP +\fIschema_name\fR +.RS 4 +The name of the schema in which to install the extension\*(Aqs objects, given that the extension allows its contents to be relocated\&. The named schema must already exist\&. If not specified, and the extension\*(Aqs control file does not specify a schema either, the current default object creation schema is used\&. +.sp +If the extension specifies a +schema +parameter in its control file, then that schema cannot be overridden with a +SCHEMA +clause\&. Normally, an error will be raised if a +SCHEMA +clause is given and it conflicts with the extension\*(Aqs +schema +parameter\&. However, if the +CASCADE +clause is also given, then +\fIschema_name\fR +is ignored when it conflicts\&. The given +\fIschema_name\fR +will be used for installation of any needed extensions that do not specify +schema +in their control files\&. +.sp +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\&. +.RE +.PP +\fIversion\fR +.RS 4 +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\*(Aqs control file\&. +.RE +.PP +CASCADE +.RS 4 +Automatically install any extensions that this extension depends on that are not already installed\&. Their dependencies are likewise automatically installed, recursively\&. The +SCHEMA +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\&. +.RE +.SH "NOTES" +.PP +Before you can use +\fBCREATE EXTENSION\fR +to load an extension into a database, the extension\*(Aqs supporting files must be installed\&. Information about installing the extensions supplied with +PostgreSQL +can be found in +Additional Supplied Modules\&. +.PP +The extensions currently available for loading can be identified from the +pg_available_extensions +or +pg_available_extension_versions +system views\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +Installing an extension as superuser requires trusting that the extension\*(Aqs 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 +\fIsearch_path\fR +during script execution, meaning that they are in the extension\*(Aqs 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\&. +.PP +The extensions supplied with +PostgreSQL +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\&. +.sp .5v +.RE +.PP +For information about writing new extensions, see +Section\ \&38.17\&. +.SH "EXAMPLES" +.PP +Install the +hstore +extension into the current database, placing its objects in schema +addons: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE EXTENSION hstore SCHEMA addons; +.fi +.if n \{\ +.RE +.\} +.sp +Another way to accomplish the same thing: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SET search_path = addons; +CREATE EXTENSION hstore; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE EXTENSION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER EXTENSION (\fBALTER_EXTENSION\fR(7)), DROP EXTENSION (\fBDROP_EXTENSION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_FOREIGN_DATA_WRAPPER.7 b/doc/src/sgml/man7/CREATE_FOREIGN_DATA_WRAPPER.7 new file mode 100644 index 0000000..f3b3711 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_FOREIGN_DATA_WRAPPER.7 @@ -0,0 +1,143 @@ +'\" t +.\" Title: CREATE FOREIGN DATA WRAPPER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE FOREIGN DATA WRAPPER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_FOREIGN_DATA_WRAPPER \- define a new foreign\-data wrapper +.SH "SYNOPSIS" +.sp +.nf +CREATE FOREIGN DATA WRAPPER \fIname\fR + [ HANDLER \fIhandler_function\fR | NO HANDLER ] + [ VALIDATOR \fIvalidator_function\fR | NO VALIDATOR ] + [ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE FOREIGN DATA WRAPPER\fR +creates a new foreign\-data wrapper\&. The user who defines a foreign\-data wrapper becomes its owner\&. +.PP +The foreign\-data wrapper name must be unique within the database\&. +.PP +Only superusers can create foreign\-data wrappers\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the foreign\-data wrapper to be created\&. +.RE +.PP +HANDLER \fIhandler_function\fR +.RS 4 +\fIhandler_function\fR +is the name of a previously registered function that will be called to retrieve the execution functions for foreign tables\&. The handler function must take no arguments, and its return type must be +fdw_handler\&. +.sp +It is possible to create a foreign\-data wrapper with no handler function, but foreign tables using such a wrapper can only be declared, not accessed\&. +.RE +.PP +VALIDATOR \fIvalidator_function\fR +.RS 4 +\fIvalidator_function\fR +is the name of a previously registered function that will be called to check the generic options given to the foreign\-data wrapper, as well as options for foreign servers, user mappings and foreign tables using the foreign\-data wrapper\&. If no validator function or +NO VALIDATOR +is specified, then options will not be checked at creation time\&. (Foreign\-data wrappers will possibly ignore or reject invalid option specifications at run time, depending on the implementation\&.) The validator function must take two arguments: one of type +text[], which will contain the array of options as stored in the system catalogs, and one of type +oid, which will be the OID of the system catalog containing the options\&. The return type is ignored; the function should report invalid options using the +\fBereport(ERROR)\fR +function\&. +.RE +.PP +OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) +.RS 4 +This clause specifies options for the new foreign\-data wrapper\&. The allowed option names and values are specific to each foreign data wrapper and are validated using the foreign\-data wrapper\*(Aqs validator function\&. Option names must be unique\&. +.RE +.SH "NOTES" +.PP +PostgreSQL\*(Aqs foreign\-data functionality is still under active development\&. Optimization of queries is primitive (and mostly left to the wrapper, too)\&. Thus, there is considerable room for future performance improvements\&. +.SH "EXAMPLES" +.PP +Create a useless foreign\-data wrapper +dummy: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FOREIGN DATA WRAPPER dummy; +.fi +.if n \{\ +.RE +.\} +.PP +Create a foreign\-data wrapper +file +with handler function +file_fdw_handler: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler; +.fi +.if n \{\ +.RE +.\} +.PP +Create a foreign\-data wrapper +mywrapper +with some options: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FOREIGN DATA WRAPPER mywrapper + OPTIONS (debug \*(Aqtrue\*(Aq); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE FOREIGN DATA WRAPPER\fR +conforms to ISO/IEC 9075\-9 (SQL/MED), with the exception that the +HANDLER +and +VALIDATOR +clauses are extensions and the standard clauses +LIBRARY +and +LANGUAGE +are not implemented in +PostgreSQL\&. +.PP +Note, however, that the SQL/MED functionality as a whole is not yet conforming\&. +.SH "SEE ALSO" +ALTER FOREIGN DATA WRAPPER (\fBALTER_FOREIGN_DATA_WRAPPER\fR(7)), DROP FOREIGN DATA WRAPPER (\fBDROP_FOREIGN_DATA_WRAPPER\fR(7)), CREATE SERVER (\fBCREATE_SERVER\fR(7)), CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7)), CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_FOREIGN_TABLE.7 b/doc/src/sgml/man7/CREATE_FOREIGN_TABLE.7 new file mode 100644 index 0000000..7720a23 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_FOREIGN_TABLE.7 @@ -0,0 +1,309 @@ +'\" t +.\" Title: CREATE FOREIGN TABLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE FOREIGN TABLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_FOREIGN_TABLE \- define a new foreign table +.SH "SYNOPSIS" +.sp +.nf +CREATE FOREIGN TABLE [ IF NOT EXISTS ] \fItable_name\fR ( [ + { \fIcolumn_name\fR \fIdata_type\fR [ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ] [ COLLATE \fIcollation\fR ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + | \fItable_constraint\fR } + [, \&.\&.\&. ] +] ) +[ INHERITS ( \fIparent_table\fR [, \&.\&.\&. ] ) ] + SERVER \fIserver_name\fR +[ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ] + +CREATE FOREIGN TABLE [ IF NOT EXISTS ] \fItable_name\fR + PARTITION OF \fIparent_table\fR [ ( + { \fIcolumn_name\fR [ WITH OPTIONS ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + | \fItable_constraint\fR } + [, \&.\&.\&. ] +) ] +{ FOR VALUES \fIpartition_bound_spec\fR | DEFAULT } + SERVER \fIserver_name\fR +[ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ] + +where \fIcolumn_constraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +{ NOT NULL | + NULL | + CHECK ( \fIexpression\fR ) [ NO INHERIT ] | + DEFAULT \fIdefault_expr\fR | + GENERATED ALWAYS AS ( \fIgeneration_expr\fR ) STORED } + +and \fItable_constraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +CHECK ( \fIexpression\fR ) [ NO INHERIT ] + +and \fIpartition_bound_spec\fR is: + +IN ( \fIpartition_bound_expr\fR [, \&.\&.\&.] ) | +FROM ( { \fIpartition_bound_expr\fR | MINVALUE | MAXVALUE } [, \&.\&.\&.] ) + TO ( { \fIpartition_bound_expr\fR | MINVALUE | MAXVALUE } [, \&.\&.\&.] ) | +WITH ( MODULUS \fInumeric_literal\fR, REMAINDER \fInumeric_literal\fR ) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE FOREIGN TABLE\fR +creates a new foreign table in the current database\&. The table will be owned by the user issuing the command\&. +.PP +If a schema name is given (for example, +CREATE FOREIGN TABLE myschema\&.mytable \&.\&.\&.) then the table is created in the specified schema\&. Otherwise it is created in the current schema\&. The name of the foreign table must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema\&. +.PP +\fBCREATE FOREIGN TABLE\fR +also automatically creates a data type that represents the composite type corresponding to one row of the foreign table\&. Therefore, foreign tables cannot have the same name as any existing data type in the same schema\&. +.PP +If +PARTITION OF +clause is specified then the table is created as a partition of +parent_table +with specified bounds\&. +.PP +To be able to create a foreign table, you must have +USAGE +privilege on the foreign server, as well as +USAGE +privilege on all column types used in the table\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a relation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing relation is anything like the one that would have been created\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table to be created\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column to be created in the new table\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The data type of the column\&. This can include array specifiers\&. For more information on the data types supported by +PostgreSQL, refer to +Chapter\ \&8\&. +.RE +.PP +COLLATE \fIcollation\fR +.RS 4 +The +COLLATE +clause assigns a collation to the column (which must be of a collatable data type)\&. If not specified, the column data type\*(Aqs default collation is used\&. +.RE +.PP +INHERITS ( \fIparent_table\fR [, \&.\&.\&. ] ) +.RS 4 +The optional +INHERITS +clause specifies a list of tables from which the new foreign table automatically inherits all columns\&. Parent tables can be plain tables or foreign tables\&. See the similar form of +\fBCREATE TABLE\fR +for more details\&. +.RE +.PP +PARTITION OF \fIparent_table\fR { FOR VALUES \fIpartition_bound_spec\fR | DEFAULT } +.RS 4 +This form can be used to create the foreign table as partition of the given parent table with specified partition bound values\&. See the similar form of +\fBCREATE TABLE\fR +for more details\&. Note that it is currently not allowed to create the foreign table as a partition of the parent table if there are +UNIQUE +indexes on the parent table\&. (See also +\fBALTER TABLE ATTACH PARTITION\fR\&.) +.RE +.PP +CONSTRAINT \fIconstraint_name\fR +.RS 4 +An optional name for a column or table constraint\&. If the constraint is violated, the constraint name is present in error messages, so constraint names like +col must be positive +can be used to communicate helpful constraint information to client applications\&. (Double\-quotes are needed to specify constraint names that contain spaces\&.) If a constraint name is not specified, the system generates a name\&. +.RE +.PP +NOT NULL +.RS 4 +The column is not allowed to contain null values\&. +.RE +.PP +NULL +.RS 4 +The column is allowed to contain null values\&. This is the default\&. +.sp +This clause is only provided for compatibility with non\-standard SQL databases\&. Its use is discouraged in new applications\&. +.RE +.PP +CHECK ( \fIexpression\fR ) [ NO INHERIT ] +.RS 4 +The +CHECK +clause specifies an expression producing a Boolean result which each row in the foreign table is expected to satisfy; that is, the expression should produce TRUE or UNKNOWN, never FALSE, for all rows in the foreign table\&. A check constraint specified as a column constraint should reference that column\*(Aqs value only, while an expression appearing in a table constraint can reference multiple columns\&. +.sp +Currently, +CHECK +expressions cannot contain subqueries nor refer to variables other than columns of the current row\&. The system column +tableoid +may be referenced, but not any other system column\&. +.sp +A constraint marked with +NO INHERIT +will not propagate to child tables\&. +.RE +.PP +DEFAULT \fIdefault_expr\fR +.RS 4 +The +DEFAULT +clause assigns a default data value for the column whose column definition it appears within\&. The value is any variable\-free expression (subqueries and cross\-references to other columns in the current table are not allowed)\&. The data type of the default expression must match the data type of the column\&. +.sp +The default expression will be used in any insert operation that does not specify a value for the column\&. If there is no default for a column, then the default is null\&. +.RE +.PP +GENERATED ALWAYS AS ( \fIgeneration_expr\fR ) STORED +.RS 4 +This clause creates the column as a +generated column\&. The column cannot be written to, and when read the result of the specified expression will be returned\&. +.sp +The keyword +STORED +is required to signify that the column will be computed on write\&. (The computed value will be presented to the foreign\-data wrapper for storage and must be returned on reading\&.) +.sp +The generation expression can refer to other columns in the table, but not other generated columns\&. Any functions and operators used must be immutable\&. References to other tables are not allowed\&. +.RE +.PP +\fIserver_name\fR +.RS 4 +The name of an existing foreign server to use for the foreign table\&. For details on defining a server, see +CREATE SERVER (\fBCREATE_SERVER\fR(7))\&. +.RE +.PP +OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&.] ) +.RS 4 +Options to be associated with the new foreign table or one of its columns\&. The allowed option names and values are specific to each foreign data wrapper and are validated using the foreign\-data wrapper\*(Aqs validator function\&. Duplicate option names are not allowed (although it\*(Aqs OK for a table option and a column option to have the same name)\&. +.RE +.SH "NOTES" +.PP +Constraints on foreign tables (such as +CHECK +or +NOT NULL +clauses) are not enforced by the core +PostgreSQL +system, and most foreign data wrappers do not attempt to enforce them either; that is, the constraint is simply assumed to hold true\&. There would be little point in such enforcement since it would only apply to rows inserted or updated via the foreign table, and not to rows modified by other means, such as directly on the remote server\&. Instead, a constraint attached to a foreign table should represent a constraint that is being enforced by the remote server\&. +.PP +Some special\-purpose foreign data wrappers might be the only access mechanism for the data they access, and in that case it might be appropriate for the foreign data wrapper itself to perform constraint enforcement\&. But you should not assume that a wrapper does that unless its documentation says so\&. +.PP +Although +PostgreSQL +does not attempt to enforce constraints on foreign tables, it does assume that they are correct for purposes of query optimization\&. If there are rows visible in the foreign table that do not satisfy a declared constraint, queries on the table might produce errors or incorrect answers\&. It is the user\*(Aqs responsibility to ensure that the constraint definition matches reality\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +When a foreign table is used as a partition of a partitioned table, there is an implicit constraint that its contents must satisfy the partitioning rule\&. Again, it is the user\*(Aqs responsibility to ensure that that is true, which is best done by installing a matching constraint on the remote server\&. +.sp .5v +.RE +.PP +Within a partitioned table containing foreign\-table partitions, an +\fBUPDATE\fR +that changes the partition key value can cause a row to be moved from a local partition to a foreign\-table partition, provided the foreign data wrapper supports tuple routing\&. However, it is not currently possible to move a row from a foreign\-table partition to another partition\&. An +\fBUPDATE\fR +that would require doing that will fail due to the partitioning constraint, assuming that that is properly enforced by the remote server\&. +.PP +Similar considerations apply to generated columns\&. Stored generated columns are computed on insert or update on the local +PostgreSQL +server and handed to the foreign\-data wrapper for writing out to the foreign data store, but it is not enforced that a query of the foreign table returns values for stored generated columns that are consistent with the generation expression\&. Again, this might result in incorrect query results\&. +.SH "EXAMPLES" +.PP +Create foreign table +films, which will be accessed through the server +film_server: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FOREIGN TABLE films ( + code char(5) NOT NULL, + title varchar(40) NOT NULL, + did integer NOT NULL, + date_prod date, + kind varchar(10), + len interval hour to minute +) +SERVER film_server; +.fi +.if n \{\ +.RE +.\} +.PP +Create foreign table +measurement_y2016m07, which will be accessed through the server +server_07, as a partition of the range partitioned table +measurement: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FOREIGN TABLE measurement_y2016m07 + PARTITION OF measurement FOR VALUES FROM (\*(Aq2016\-07\-01\*(Aq) TO (\*(Aq2016\-08\-01\*(Aq) + SERVER server_07; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBCREATE FOREIGN TABLE\fR +command largely conforms to the +SQL +standard; however, much as with +\fBCREATE TABLE\fR, +NULL +constraints and zero\-column foreign tables are permitted\&. The ability to specify column default values is also a +PostgreSQL +extension\&. Table inheritance, in the form defined by +PostgreSQL, is nonstandard\&. +.SH "SEE ALSO" +ALTER FOREIGN TABLE (\fBALTER_FOREIGN_TABLE\fR(7)), DROP FOREIGN TABLE (\fBDROP_FOREIGN_TABLE\fR(7)), CREATE TABLE (\fBCREATE_TABLE\fR(7)), CREATE SERVER (\fBCREATE_SERVER\fR(7)), IMPORT FOREIGN SCHEMA (\fBIMPORT_FOREIGN_SCHEMA\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_FUNCTION.7 b/doc/src/sgml/man7/CREATE_FUNCTION.7 new file mode 100644 index 0000000..0cb288a --- /dev/null +++ b/doc/src/sgml/man7/CREATE_FUNCTION.7 @@ -0,0 +1,781 @@ +'\" t +.\" Title: CREATE FUNCTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE FUNCTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_FUNCTION \- define a new function +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] FUNCTION + \fIname\fR ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ { DEFAULT | = } \fIdefault_expr\fR ] [, \&.\&.\&.] ] ) + [ RETURNS \fIrettype\fR + | RETURNS TABLE ( \fIcolumn_name\fR \fIcolumn_type\fR [, \&.\&.\&.] ) ] + { LANGUAGE \fIlang_name\fR + | TRANSFORM { FOR TYPE \fItype_name\fR } [, \&.\&.\&. ] + | WINDOW + | { IMMUTABLE | STABLE | VOLATILE } + | [ NOT ] LEAKPROOF + | { CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT } + | { [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER } + | PARALLEL { UNSAFE | RESTRICTED | SAFE } + | COST \fIexecution_cost\fR + | ROWS \fIresult_rows\fR + | SUPPORT \fIsupport_function\fR + | SET \fIconfiguration_parameter\fR { TO \fIvalue\fR | = \fIvalue\fR | FROM CURRENT } + | AS \*(Aq\fIdefinition\fR\*(Aq + | AS \*(Aq\fIobj_file\fR\*(Aq, \*(Aq\fIlink_symbol\fR\*(Aq + | \fIsql_body\fR + } \&.\&.\&. +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE FUNCTION\fR +defines a new function\&. +\fBCREATE OR REPLACE FUNCTION\fR +will either create a new function, or replace an existing definition\&. To be able to define a function, the user must have the +USAGE +privilege on the language\&. +.PP +If a schema name is included, then the function is created in the specified schema\&. Otherwise it is created in the current schema\&. The name of the new function must not match any existing function or procedure with the same input argument types in the same schema\&. However, functions and procedures of different argument types can share a name (this is called +overloading)\&. +.PP +To replace the current definition of an existing function, use +\fBCREATE OR REPLACE FUNCTION\fR\&. It is not possible to change the name or argument types of a function this way (if you tried, you would actually be creating a new, distinct function)\&. Also, +\fBCREATE OR REPLACE FUNCTION\fR +will not let you change the return type of an existing function\&. To do that, you must drop and recreate the function\&. (When using +OUT +parameters, that means you cannot change the types of any +OUT +parameters except by dropping the function\&.) +.PP +When +\fBCREATE OR REPLACE FUNCTION\fR +is used to replace an existing function, the ownership and permissions of the function do not change\&. All other function properties are assigned the values specified or implied in the command\&. You must own the function to replace it (this includes being a member of the owning role)\&. +.PP +If you drop and then recreate a function, the new function is not the same entity as the old; you will have to drop existing rules, views, triggers, etc\&. that refer to the old function\&. Use +\fBCREATE OR REPLACE FUNCTION\fR +to change a function definition without breaking objects that refer to the function\&. Also, +\fBALTER FUNCTION\fR +can be used to change most of the auxiliary properties of an existing function\&. +.PP +The user that creates the function becomes the owner of the function\&. +.PP +To be able to create a function, you must have +USAGE +privilege on the argument types and the return type\&. +.PP +Refer to +Section\ \&38.3 +for further information on writing functions\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the function to create\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. Only +OUT +arguments can follow a +VARIADIC +one\&. Also, +OUT +and +INOUT +arguments cannot be used together with the +RETURNS TABLE +notation\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Some languages (including SQL and PL/pgSQL) let you use the name in the function body\&. For other languages the name of an input argument is just extra documentation, so far as the function itself is concerned; but you can use input argument names when calling a function to improve readability (see +Section\ \&4.3)\&. In any case, the name of an output argument is significant, because it defines the column name in the result row type\&. (If you omit the name for an output argument, the system will choose a default column name\&.) +.RE +.PP +\fIargtype\fR +.RS 4 +The data type(s) of the function\*(Aqs arguments (optionally schema\-qualified), if any\&. The argument types can be base, composite, or domain types, or can reference the type of a table column\&. +.sp +Depending on the implementation language it might also be allowed to specify +\(lqpseudo\-types\(rq +such as +cstring\&. Pseudo\-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types\&. +.sp +The type of a column is referenced by writing +\fItable_name\fR\&.\fIcolumn_name\fR%TYPE\&. Using this feature can sometimes help make a function independent of changes to the definition of a table\&. +.RE +.PP +\fIdefault_expr\fR +.RS 4 +An expression to be used as default value if the parameter is not specified\&. The expression has to be coercible to the argument type of the parameter\&. Only input (including +INOUT) parameters can have a default value\&. All input parameters following a parameter with a default value must have default values as well\&. +.RE +.PP +\fIrettype\fR +.RS 4 +The return data type (optionally schema\-qualified)\&. The return type can be a base, composite, or domain type, or can reference the type of a table column\&. Depending on the implementation language it might also be allowed to specify +\(lqpseudo\-types\(rq +such as +cstring\&. If the function is not supposed to return a value, specify +void +as the return type\&. +.sp +When there are +OUT +or +INOUT +parameters, the +RETURNS +clause can be omitted\&. If present, it must agree with the result type implied by the output parameters: +RECORD +if there are multiple output parameters, or the same type as the single output parameter\&. +.sp +The +SETOF +modifier indicates that the function will return a set of items, rather than a single item\&. +.sp +The type of a column is referenced by writing +\fItable_name\fR\&.\fIcolumn_name\fR%TYPE\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of an output column in the +RETURNS TABLE +syntax\&. This is effectively another way of declaring a named +OUT +parameter, except that +RETURNS TABLE +also implies +RETURNS SETOF\&. +.RE +.PP +\fIcolumn_type\fR +.RS 4 +The data type of an output column in the +RETURNS TABLE +syntax\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the language that the function is implemented in\&. It can be +sql, +c, +internal, or the name of a user\-defined procedural language, e\&.g\&., +plpgsql\&. The default is +sql +if +\fIsql_body\fR +is specified\&. Enclosing the name in single quotes is deprecated and requires matching case\&. +.RE +.PP +TRANSFORM { FOR TYPE \fItype_name\fR } [, \&.\&.\&. ] } +.RS 4 +Lists which transforms a call to the function should apply\&. Transforms convert between SQL types and language\-specific data types; see +CREATE TRANSFORM (\fBCREATE_TRANSFORM\fR(7))\&. Procedural language implementations usually have hardcoded knowledge of the built\-in types, so those don\*(Aqt need to be listed here\&. If a procedural language implementation does not know how to handle a type and no transform is supplied, it will fall back to a default behavior for converting data types, but this depends on the implementation\&. +.RE +.PP +WINDOW +.RS 4 +WINDOW +indicates that the function is a +window function +rather than a plain function\&. This is currently only useful for functions written in C\&. The +WINDOW +attribute cannot be changed when replacing an existing function definition\&. +.RE +.PP +IMMUTABLE +.br +STABLE +.br +VOLATILE +.RS 4 +These attributes inform the query optimizer about the behavior of the function\&. At most one choice can be specified\&. If none of these appear, +VOLATILE +is the default assumption\&. +.sp +IMMUTABLE +indicates that the function cannot modify the database and always returns the same result when given the same argument values; that is, it does not do database lookups or otherwise use information not directly present in its argument list\&. If this option is given, any call of the function with all\-constant arguments can be immediately replaced with the function value\&. +.sp +STABLE +indicates that the function cannot modify the database, and that within a single table scan it will consistently return the same result for the same argument values, but that its result could change across SQL statements\&. This is the appropriate selection for functions whose results depend on database lookups, parameter variables (such as the current time zone), etc\&. (It is inappropriate for +AFTER +triggers that wish to query rows modified by the current command\&.) Also note that the +\fBcurrent_timestamp\fR +family of functions qualify as stable, since their values do not change within a transaction\&. +.sp +VOLATILE +indicates that the function value can change even within a single table scan, so no optimizations can be made\&. Relatively few database functions are volatile in this sense; some examples are +random(), +currval(), +timeofday()\&. But note that any function that has side\-effects must be classified volatile, even if its result is quite predictable, to prevent calls from being optimized away; an example is +setval()\&. +.sp +For additional details see +Section\ \&38.7\&. +.RE +.PP +LEAKPROOF +.RS 4 +LEAKPROOF +indicates that the function has no side effects\&. It reveals no information about its arguments other than by its return value\&. For example, a function which throws an error message for some argument values but not others, or which includes the argument values in any error message, is not leakproof\&. This affects how the system executes queries against views created with the +security_barrier +option or tables with row level security enabled\&. The system will enforce conditions from security policies and security barrier views before any user\-supplied conditions from the query itself that contain non\-leakproof functions, in order to prevent the inadvertent exposure of data\&. Functions and operators marked as leakproof are assumed to be trustworthy, and may be executed before conditions from security policies and security barrier views\&. In addition, functions which do not take arguments or which are not passed any arguments from the security barrier view or table do not have to be marked as leakproof to be executed before security conditions\&. See +CREATE VIEW (\fBCREATE_VIEW\fR(7)) +and +Section\ \&41.5\&. This option can only be set by the superuser\&. +.RE +.PP +CALLED ON NULL INPUT +.br +RETURNS NULL ON NULL INPUT +.br +STRICT +.RS 4 +CALLED ON NULL INPUT +(the default) indicates that the function will be called normally when some of its arguments are null\&. It is then the function author\*(Aqs responsibility to check for null values if necessary and respond appropriately\&. +.sp +RETURNS NULL ON NULL INPUT +or +STRICT +indicates that the function always returns null whenever any of its arguments are null\&. If this parameter is specified, the function is not executed when there are null arguments; instead a null result is assumed automatically\&. +.RE +.PP +[EXTERNAL] SECURITY INVOKER +.br +[EXTERNAL] SECURITY DEFINER +.RS 4 +SECURITY INVOKER +indicates that the function is to be executed with the privileges of the user that calls it\&. That is the default\&. +SECURITY DEFINER +specifies that the function is to be executed with the privileges of the user that owns it\&. +.sp +The key word +EXTERNAL +is allowed for SQL conformance, but it is optional since, unlike in SQL, this feature applies to all functions not only external ones\&. +.RE +.PP +PARALLEL +.RS 4 +PARALLEL UNSAFE +indicates that the function can\*(Aqt be executed in parallel mode and the presence of such a function in an SQL statement forces a serial execution plan\&. This is the default\&. +PARALLEL RESTRICTED +indicates that the function can be executed in parallel mode, but the execution is restricted to parallel group leader\&. +PARALLEL SAFE +indicates that the function is safe to run in parallel mode without restriction\&. +.sp +Functions should be labeled parallel unsafe if they modify any database state, or if they make changes to the transaction such as using sub\-transactions, or if they access sequences or attempt to make persistent changes to settings (e\&.g\&., +setval)\&. They should be labeled as parallel restricted if they access temporary tables, client connection state, cursors, prepared statements, or miscellaneous backend\-local state which the system cannot synchronize in parallel mode (e\&.g\&., +setseed +cannot be executed other than by the group leader because a change made by another process would not be reflected in the leader)\&. In general, if a function is labeled as being safe when it is restricted or unsafe, or if it is labeled as being restricted when it is in fact unsafe, it may throw errors or produce wrong answers when used in a parallel query\&. C\-language functions could in theory exhibit totally undefined behavior if mislabeled, since there is no way for the system to protect itself against arbitrary C code, but in most likely cases the result will be no worse than for any other function\&. If in doubt, functions should be labeled as +UNSAFE, which is the default\&. +.RE +.PP +COST \fIexecution_cost\fR +.RS 4 +A positive number giving the estimated execution cost for the function, in units of +cpu_operator_cost\&. If the function returns a set, this is the cost per returned row\&. If the cost is not specified, 1 unit is assumed for C\-language and internal functions, and 100 units for functions in all other languages\&. Larger values cause the planner to try to avoid evaluating the function more often than necessary\&. +.RE +.PP +ROWS \fIresult_rows\fR +.RS 4 +A positive number giving the estimated number of rows that the planner should expect the function to return\&. This is only allowed when the function is declared to return a set\&. The default assumption is 1000 rows\&. +.RE +.PP +SUPPORT \fIsupport_function\fR +.RS 4 +The name (optionally schema\-qualified) of a +planner support function +to use for this function\&. See +Section\ \&38.11 +for details\&. You must be superuser to use this option\&. +.RE +.PP +\fIconfiguration_parameter\fR +.br +\fIvalue\fR +.RS 4 +The +SET +clause causes the specified configuration parameter to be set to the specified value when the function is entered, and then restored to its prior value when the function exits\&. +SET FROM CURRENT +saves the value of the parameter that is current when +\fBCREATE FUNCTION\fR +is executed as the value to be applied when the function is entered\&. +.sp +If a +SET +clause is attached to a function, then the effects of a +\fBSET LOCAL\fR +command executed inside the function for the same variable are restricted to the function: the configuration parameter\*(Aqs prior value is still restored at function exit\&. However, an ordinary +\fBSET\fR +command (without +LOCAL) overrides the +SET +clause, much as it would do for a previous +\fBSET LOCAL\fR +command: the effects of such a command will persist after function exit, unless the current transaction is rolled back\&. +.sp +See +\fBSET\fR(7) +and +Chapter\ \&20 +for more information about allowed parameter names and values\&. +.RE +.PP +\fIdefinition\fR +.RS 4 +A string constant defining the function; the meaning depends on the language\&. It can be an internal function name, the path to an object file, an SQL command, or text in a procedural language\&. +.sp +It is often helpful to use dollar quoting (see +Section\ \&4.1.2.4) to write the function definition string, rather than the normal single quote syntax\&. Without dollar quoting, any single quotes or backslashes in the function definition must be escaped by doubling them\&. +.RE +.PP +\fIobj_file\fR, \fIlink_symbol\fR +.RS 4 +This form of the +AS +clause is used for dynamically loadable C language functions when the function name in the C language source code is not the same as the name of the SQL function\&. The string +\fIobj_file\fR +is the name of the shared library file containing the compiled C function, and is interpreted as for the +\fBLOAD\fR +command\&. The string +\fIlink_symbol\fR +is the function\*(Aqs link symbol, that is, the name of the function in the C language source code\&. If the link symbol is omitted, it is assumed to be the same as the name of the SQL function being defined\&. The C names of all functions must be different, so you must give overloaded C functions different C names (for example, use the argument types as part of the C names)\&. +.sp +When repeated +\fBCREATE FUNCTION\fR +calls refer to the same object file, the file is only loaded once per session\&. To unload and reload the file (perhaps during development), start a new session\&. +.RE +.PP +\fIsql_body\fR +.RS 4 +The body of a +LANGUAGE SQL +function\&. This can either be a single statement +.sp +.if n \{\ +.RS 4 +.\} +.nf +RETURN \fIexpression\fR +.fi +.if n \{\ +.RE +.\} +.sp +or a block +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN ATOMIC + \fIstatement\fR; + \fIstatement\fR; + \&.\&.\&. + \fIstatement\fR; +END +.fi +.if n \{\ +.RE +.\} +.sp +This is similar to writing the text of the function body as a string constant (see +\fIdefinition\fR +above), but there are some differences: This form only works for +LANGUAGE SQL, the string constant form works for all languages\&. This form is parsed at function definition time, the string constant form is parsed at execution time; therefore this form cannot support polymorphic argument types and other constructs that are not resolvable at function definition time\&. This form tracks dependencies between the function and objects used in the function body, so +DROP \&.\&.\&. CASCADE +will work correctly, whereas the form using string literals may leave dangling functions\&. Finally, this form is more compatible with the SQL standard and other SQL implementations\&. +.RE +.SH "OVERLOADING" +.PP +PostgreSQL +allows function +overloading; that is, the same name can be used for several different functions so long as they have distinct input argument types\&. Whether or not you use it, this capability entails security precautions when calling functions in databases where some users mistrust other users; see +Section\ \&10.3\&. +.PP +Two functions are considered the same if they have the same names and +\fIinput\fR +argument types, ignoring any +OUT +parameters\&. Thus for example these declarations conflict: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION foo(int) \&.\&.\&. +CREATE FUNCTION foo(int, out text) \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.PP +Functions that have different argument type lists will not be considered to conflict at creation time, but if defaults are provided they might conflict in use\&. For example, consider +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION foo(int) \&.\&.\&. +CREATE FUNCTION foo(int, int default 42) \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.sp +A call +foo(10) +will fail due to the ambiguity about which function should be called\&. +.SH "NOTES" +.PP +The full +SQL +type syntax is allowed for declaring a function\*(Aqs arguments and return value\&. However, parenthesized type modifiers (e\&.g\&., the precision field for type +numeric) are discarded by +\fBCREATE FUNCTION\fR\&. Thus for example +CREATE FUNCTION foo (varchar(10)) \&.\&.\&. +is exactly the same as +CREATE FUNCTION foo (varchar) \&.\&.\&.\&. +.PP +When replacing an existing function with +\fBCREATE OR REPLACE FUNCTION\fR, there are restrictions on changing parameter names\&. You cannot change the name already assigned to any input parameter (although you can add names to parameters that had none before)\&. If there is more than one output parameter, you cannot change the names of the output parameters, because that would change the column names of the anonymous composite type that describes the function\*(Aqs result\&. These restrictions are made to ensure that existing calls of the function do not stop working when it is replaced\&. +.PP +If a function is declared +STRICT +with a +VARIADIC +argument, the strictness check tests that the variadic array +\fIas a whole\fR +is non\-null\&. The function will still be called if the array has null elements\&. +.SH "EXAMPLES" +.PP +Add two integers using an SQL function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION add(integer, integer) RETURNS integer + AS \*(Aqselect $1 + $2;\*(Aq + LANGUAGE SQL + IMMUTABLE + RETURNS NULL ON NULL INPUT; +.fi +.if n \{\ +.RE +.\} +.sp +The same function written in a more SQL\-conforming style, using argument names and an unquoted body: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION add(a integer, b integer) RETURNS integer + LANGUAGE SQL + IMMUTABLE + RETURNS NULL ON NULL INPUT + RETURN a + b; +.fi +.if n \{\ +.RE +.\} +.PP +Increment an integer, making use of an argument name, in +PL/pgSQL: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$ + BEGIN + RETURN i + 1; + END; +$$ LANGUAGE plpgsql; +.fi +.if n \{\ +.RE +.\} +.PP +Return a record containing multiple output parameters: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION dup(in int, out f1 int, out f2 text) + AS $$ SELECT $1, CAST($1 AS text) || \*(Aq is text\*(Aq $$ + LANGUAGE SQL; + +SELECT * FROM dup(42); +.fi +.if n \{\ +.RE +.\} +.sp +You can do the same thing more verbosely with an explicitly named composite type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE dup_result AS (f1 int, f2 text); + +CREATE FUNCTION dup(int) RETURNS dup_result + AS $$ SELECT $1, CAST($1 AS text) || \*(Aq is text\*(Aq $$ + LANGUAGE SQL; + +SELECT * FROM dup(42); +.fi +.if n \{\ +.RE +.\} +.sp +Another way to return multiple columns is to use a +TABLE +function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) + AS $$ SELECT $1, CAST($1 AS text) || \*(Aq is text\*(Aq $$ + LANGUAGE SQL; + +SELECT * FROM dup(42); +.fi +.if n \{\ +.RE +.\} +.sp +However, a +TABLE +function is different from the preceding examples, because it actually returns a +\fIset\fR +of records, not just one record\&. +.SH "WRITING SECURITY DEFINER FUNCTIONS SAFELY" +.PP +Because a +SECURITY DEFINER +function is executed with the privileges of the user that owns it, care is needed to ensure that the function cannot be misused\&. For security, +search_path +should be set to exclude any schemas writable by untrusted users\&. This prevents malicious users from creating objects (e\&.g\&., tables, functions, and operators) that mask objects intended to be used by the function\&. Particularly important in this regard is the temporary\-table schema, which is searched first by default, and is normally writable by anyone\&. A secure arrangement can be obtained by forcing the temporary schema to be searched last\&. To do this, write +pg_temp +as the last entry in +\fIsearch_path\fR\&. This function illustrates safe usage: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION check_password(uname TEXT, pass TEXT) +RETURNS BOOLEAN AS $$ +DECLARE passed BOOLEAN; +BEGIN + SELECT (pwd = $2) INTO passed + FROM pwds + WHERE username = $1; + + RETURN passed; +END; +$$ LANGUAGE plpgsql + SECURITY DEFINER + \-\- Set a secure search_path: trusted schema(s), then \*(Aqpg_temp\*(Aq\&. + SET search_path = admin, pg_temp; +.fi +.if n \{\ +.RE +.\} +.sp +This function\*(Aqs intention is to access a table +admin\&.pwds\&. But without the +SET +clause, or with a +SET +clause mentioning only +admin, the function could be subverted by creating a temporary table named +pwds\&. +.PP +Before +PostgreSQL +version 8\&.3, the +SET +clause was not available, and so older functions may contain rather complicated logic to save, set, and restore +\fIsearch_path\fR\&. The +SET +clause is far easier to use for this purpose\&. +.PP +Another point to keep in mind is that by default, execute privilege is granted to +PUBLIC +for newly created functions (see +Section\ \&5.7 +for more information)\&. Frequently you will wish to restrict use of a security definer function to only some users\&. To do that, you must revoke the default +PUBLIC +privileges and then grant execute privilege selectively\&. To avoid having a window where the new function is accessible to all, create it and set the privileges within a single transaction\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; +CREATE FUNCTION check_password(uname TEXT, pass TEXT) \&.\&.\&. SECURITY DEFINER; +REVOKE ALL ON FUNCTION check_password(uname TEXT, pass TEXT) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION check_password(uname TEXT, pass TEXT) TO admins; +COMMIT; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +A +\fBCREATE FUNCTION\fR +command is defined in the SQL standard\&. The +PostgreSQL +implementation can be used in a compatible way but has many extensions\&. Conversely, the SQL standard specifies a number of optional features that are not implemented in +PostgreSQL\&. +.PP +The following are important compatibility issues: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +OR REPLACE +is a PostgreSQL extension\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For compatibility with some other database systems, +\fIargmode\fR +can be written either before or after +\fIargname\fR\&. But only the first way is standard\-compliant\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For parameter defaults, the SQL standard specifies only the syntax with the +DEFAULT +key word\&. The syntax with += +is used in T\-SQL and Firebird\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +SETOF +modifier is a PostgreSQL extension\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Only +SQL +is standardized as a language\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +All other attributes except +CALLED ON NULL INPUT +and +RETURNS NULL ON NULL INPUT +are not standardized\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +For the body of +LANGUAGE SQL +functions, the SQL standard only specifies the +\fIsql_body\fR +form\&. +.RE +.PP +Simple +LANGUAGE SQL +functions can be written in a way that is both standard\-conforming and portable to other implementations\&. More complex functions using advanced features, optimization attributes, or other languages will necessarily be specific to PostgreSQL in a significant way\&. +.SH "SEE ALSO" +ALTER FUNCTION (\fBALTER_FUNCTION\fR(7)), DROP FUNCTION (\fBDROP_FUNCTION\fR(7)), \fBGRANT\fR(7), \fBLOAD\fR(7), \fBREVOKE\fR(7) diff --git a/doc/src/sgml/man7/CREATE_GROUP.7 b/doc/src/sgml/man7/CREATE_GROUP.7 new file mode 100644 index 0000000..ed6670f --- /dev/null +++ b/doc/src/sgml/man7/CREATE_GROUP.7 @@ -0,0 +1,67 @@ +'\" t +.\" Title: CREATE GROUP +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE GROUP" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_GROUP \- define a new database role +.SH "SYNOPSIS" +.sp +.nf +CREATE GROUP \fIname\fR [ [ WITH ] \fIoption\fR [ \&.\&.\&. ] ] + +where \fIoption\fR can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | REPLICATION | NOREPLICATION + | BYPASSRLS | NOBYPASSRLS + | CONNECTION LIMIT \fIconnlimit\fR + | [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq | PASSWORD NULL + | VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq + | IN ROLE \fIrole_name\fR [, \&.\&.\&.] + | IN GROUP \fIrole_name\fR [, \&.\&.\&.] + | ROLE \fIrole_name\fR [, \&.\&.\&.] + | ADMIN \fIrole_name\fR [, \&.\&.\&.] + | USER \fIrole_name\fR [, \&.\&.\&.] + | SYSID \fIuid\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE GROUP\fR +is now an alias for +CREATE ROLE (\fBCREATE_ROLE\fR(7))\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE GROUP\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE ROLE (\fBCREATE_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_INDEX.7 b/doc/src/sgml/man7/CREATE_INDEX.7 new file mode 100644 index 0000000..3bbfaae --- /dev/null +++ b/doc/src/sgml/man7/CREATE_INDEX.7 @@ -0,0 +1,766 @@ +'\" t +.\" Title: CREATE INDEX +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE INDEX" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_INDEX \- define a new index +.SH "SYNOPSIS" +.sp +.nf +CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] \fIname\fR ] ON [ ONLY ] \fItable_name\fR [ USING \fImethod\fR ] + ( { \fIcolumn_name\fR | ( \fIexpression\fR ) } [ COLLATE \fIcollation\fR ] [ \fIopclass\fR [ ( \fIopclass_parameter\fR = \fIvalue\fR [, \&.\&.\&. ] ) ] ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, \&.\&.\&.] ) + [ INCLUDE ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] + [ NULLS [ NOT ] DISTINCT ] + [ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] + [ TABLESPACE \fItablespace_name\fR ] + [ WHERE \fIpredicate\fR ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE INDEX\fR +constructs an index on the specified column(s) of the specified relation, which can be a table or a materialized view\&. Indexes are primarily used to enhance database performance (though inappropriate use can result in slower performance)\&. +.PP +The key field(s) for the index are specified as column names, or alternatively as expressions written in parentheses\&. Multiple fields can be specified if the index method supports multicolumn indexes\&. +.PP +An index field can be an expression computed from the values of one or more columns of the table row\&. This feature can be used to obtain fast access to data based on some transformation of the basic data\&. For example, an index computed on +upper(col) +would allow the clause +WHERE upper(col) = \*(AqJIM\*(Aq +to use an index\&. +.PP +PostgreSQL +provides the index methods B\-tree, hash, GiST, SP\-GiST, GIN, and BRIN\&. Users can also define their own index methods, but that is fairly complicated\&. +.PP +When the +WHERE +clause is present, a +partial index +is created\&. A partial index is an index that contains entries for only a portion of a table, usually a portion that is more useful for indexing than the rest of the table\&. For example, if you have a table that contains both billed and unbilled orders where the unbilled orders take up a small fraction of the total table and yet that is an often used section, you can improve performance by creating an index on just that portion\&. Another possible application is to use +WHERE +with +UNIQUE +to enforce uniqueness over a subset of a table\&. See +Section\ \&11.8 +for more discussion\&. +.PP +The expression used in the +WHERE +clause can refer only to columns of the underlying table, but it can use all columns, not just the ones being indexed\&. Presently, subqueries and aggregate expressions are also forbidden in +WHERE\&. The same restrictions apply to index fields that are expressions\&. +.PP +All functions and operators used in an index definition must be +\(lqimmutable\(rq, that is, their results must depend only on their arguments and never on any outside influence (such as the contents of another table or the current time)\&. This restriction ensures that the behavior of the index is well\-defined\&. To use a user\-defined function in an index expression or +WHERE +clause, remember to mark the function immutable when you create it\&. +.SH "PARAMETERS" +.PP +UNIQUE +.RS 4 +Causes the system to check for duplicate values in the table when the index is created (if data already exist) and each time data is added\&. Attempts to insert or update data which would result in duplicate entries will generate an error\&. +.sp +Additional restrictions apply when unique indexes are applied to partitioned tables; see +CREATE TABLE (\fBCREATE_TABLE\fR(7))\&. +.RE +.PP +CONCURRENTLY +.RS 4 +When this option is used, +PostgreSQL +will build the index without taking any locks that prevent concurrent inserts, updates, or deletes on the table; whereas a standard index build locks out writes (but not reads) on the table until it\*(Aqs done\&. There are several caveats to be aware of when using this option \(em see +Building Indexes Concurrently +below\&. +.sp +For temporary tables, +\fBCREATE INDEX\fR +is always non\-concurrent, as no other session can access them, and non\-concurrent index creation is cheaper\&. +.RE +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a relation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing index is anything like the one that would have been created\&. Index name is required when +IF NOT EXISTS +is specified\&. +.RE +.PP +INCLUDE +.RS 4 +The optional +INCLUDE +clause specifies a list of columns which will be included in the index as +non\-key +columns\&. A non\-key column cannot be used in an index scan search qualification, and it is disregarded for purposes of any uniqueness or exclusion constraint enforced by the index\&. However, an index\-only scan can return the contents of non\-key columns without having to visit the index\*(Aqs table, since they are available directly from the index entry\&. Thus, addition of non\-key columns allows index\-only scans to be used for queries that otherwise could not use them\&. +.sp +It\*(Aqs wise to be conservative about adding non\-key columns to an index, especially wide columns\&. If an index tuple exceeds the maximum size allowed for the index type, data insertion will fail\&. In any case, non\-key columns duplicate data from the index\*(Aqs table and bloat the size of the index, thus potentially slowing searches\&. Furthermore, B\-tree deduplication is never used with indexes that have a non\-key column\&. +.sp +Columns listed in the +INCLUDE +clause don\*(Aqt need appropriate operator classes; the clause can include columns whose data types don\*(Aqt have operator classes defined for a given access method\&. +.sp +Expressions are not supported as included columns since they cannot be used in index\-only scans\&. +.sp +Currently, the B\-tree, GiST and SP\-GiST index access methods support this feature\&. In these indexes, the values of columns listed in the +INCLUDE +clause are included in leaf tuples which correspond to heap tuples, but are not included in upper\-level index entries used for tree navigation\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the index to be created\&. No schema name can be included here; the index is always created in the same schema as its parent table\&. The name of the index must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in that schema\&. If the name is omitted, +PostgreSQL +chooses a suitable name based on the parent table\*(Aqs name and the indexed column name(s)\&. +.RE +.PP +ONLY +.RS 4 +Indicates not to recurse creating indexes on partitions, if the table is partitioned\&. The default is to recurse\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (possibly schema\-qualified) of the table to be indexed\&. +.RE +.PP +\fImethod\fR +.RS 4 +The name of the index method to be used\&. Choices are +btree, +hash, +gist, +spgist, +gin, +brin, or user\-installed access methods like +bloom\&. The default method is +btree\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column of the table\&. +.RE +.PP +\fIexpression\fR +.RS 4 +An expression based on one or more columns of the table\&. The expression usually must be written with surrounding parentheses, as shown in the syntax\&. However, the parentheses can be omitted if the expression has the form of a function call\&. +.RE +.PP +\fIcollation\fR +.RS 4 +The name of the collation to use for the index\&. By default, the index uses the collation declared for the column to be indexed or the result collation of the expression to be indexed\&. Indexes with non\-default collations can be useful for queries that involve expressions using non\-default collations\&. +.RE +.PP +\fIopclass\fR +.RS 4 +The name of an operator class\&. See below for details\&. +.RE +.PP +\fIopclass_parameter\fR +.RS 4 +The name of an operator class parameter\&. See below for details\&. +.RE +.PP +ASC +.RS 4 +Specifies ascending sort order (which is the default)\&. +.RE +.PP +DESC +.RS 4 +Specifies descending sort order\&. +.RE +.PP +NULLS FIRST +.RS 4 +Specifies that nulls sort before non\-nulls\&. This is the default when +DESC +is specified\&. +.RE +.PP +NULLS LAST +.RS 4 +Specifies that nulls sort after non\-nulls\&. This is the default when +DESC +is not specified\&. +.RE +.PP +NULLS DISTINCT +.br +NULLS NOT DISTINCT +.RS 4 +Specifies whether for a unique index, null values should be considered distinct (not equal)\&. The default is that they are distinct, so that a unique index could contain multiple null values in a column\&. +.RE +.PP +\fIstorage_parameter\fR +.RS 4 +The name of an index\-method\-specific storage parameter\&. See +Index Storage Parameters +below for details\&. +.RE +.PP +\fItablespace_name\fR +.RS 4 +The tablespace in which to create the index\&. If not specified, +default_tablespace +is consulted, or +temp_tablespaces +for indexes on temporary tables\&. +.RE +.PP +\fIpredicate\fR +.RS 4 +The constraint expression for a partial index\&. +.RE +.SS "Index Storage Parameters" +.PP +The optional +WITH +clause specifies +storage parameters +for the index\&. Each index method has its own set of allowed storage parameters\&. The B\-tree, hash, GiST and SP\-GiST index methods all accept this parameter: +.PP +fillfactor (integer) +.RS 4 +The fillfactor for an index is a percentage that determines how full the index method will try to pack index pages\&. For B\-trees, leaf pages are filled to this percentage during initial index builds, and also when extending the index at the right (adding new largest key values)\&. If pages subsequently become completely full, they will be split, leading to fragmentation of the on\-disk index structure\&. B\-trees use a default fillfactor of 90, but any integer value from 10 to 100 can be selected\&. +.sp +B\-tree indexes on tables where many inserts and/or updates are anticipated can benefit from lower fillfactor settings at +\fBCREATE INDEX\fR +time (following bulk loading into the table)\&. Values in the range of 50 \- 90 can usefully +\(lqsmooth out\(rq +the +\fIrate\fR +of page splits during the early life of the B\-tree index (lowering fillfactor like this may even lower the absolute number of page splits, though this effect is highly workload dependent)\&. The B\-tree bottom\-up index deletion technique described in +Section\ \&67.4.2 +is dependent on having some +\(lqextra\(rq +space on pages to store +\(lqextra\(rq +tuple versions, and so can be affected by fillfactor (though the effect is usually not significant)\&. +.sp +In other specific cases it might be useful to increase fillfactor to 100 at +\fBCREATE INDEX\fR +time as a way of maximizing space utilization\&. You should only consider this when you are completely sure that the table is static (i\&.e\&. that it will never be affected by either inserts or updates)\&. A fillfactor setting of 100 otherwise risks +\fIharming\fR +performance: even a few updates or inserts will cause a sudden flood of page splits\&. +.sp +The other index methods use fillfactor in different but roughly analogous ways; the default fillfactor varies between methods\&. +.RE +.PP +B\-tree indexes additionally accept this parameter: +.PP +deduplicate_items (boolean) +.RS 4 +Controls usage of the B\-tree deduplication technique described in +Section\ \&67.4.3\&. Set to +ON +or +OFF +to enable or disable the optimization\&. (Alternative spellings of +ON +and +OFF +are allowed as described in +Section\ \&20.1\&.) The default is +ON\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Turning +deduplicate_items +off via +\fBALTER INDEX\fR +prevents future insertions from triggering deduplication, but does not in itself make existing posting list tuples use the standard tuple representation\&. +.sp .5v +.RE +.RE +.PP +GiST indexes additionally accept this parameter: +.PP +buffering (enum) +.RS 4 +Determines whether the buffered build technique described in +Section\ \&68.4.1 +is used to build the index\&. With +OFF +buffering is disabled, with +ON +it is enabled, and with +AUTO +it is initially disabled, but is turned on on\-the\-fly once the index size reaches +effective_cache_size\&. The default is +AUTO\&. Note that if sorted build is possible, it will be used instead of buffered build unless +buffering=ON +is specified\&. +.RE +.PP +GIN indexes accept different parameters: +.PP +fastupdate (boolean) +.RS 4 +This setting controls usage of the fast update technique described in +Section\ \&70.4.1\&. It is a Boolean parameter: +ON +enables fast update, +OFF +disables it\&. The default is +ON\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Turning +fastupdate +off via +\fBALTER INDEX\fR +prevents future insertions from going into the list of pending index entries, but does not in itself flush previous entries\&. You might want to +\fBVACUUM\fR +the table or call +\fBgin_clean_pending_list\fR +function afterward to ensure the pending list is emptied\&. +.sp .5v +.RE +.RE +.PP +gin_pending_list_limit (integer) +.RS 4 +Custom +gin_pending_list_limit +parameter\&. This value is specified in kilobytes\&. +.RE +.PP +BRIN +indexes accept different parameters: +.PP +pages_per_range (integer) +.RS 4 +Defines the number of table blocks that make up one block range for each entry of a +BRIN +index (see +Section\ \&71.1 +for more details)\&. The default is +128\&. +.RE +.PP +autosummarize (boolean) +.RS 4 +Defines whether a summarization run is queued for the previous page range whenever an insertion is detected on the next one\&. See +Section\ \&71.1.1 +for more details\&. The default is +off\&. +.RE +.SS "Building Indexes Concurrently" +.PP +Creating an index can interfere with regular operation of a database\&. Normally +PostgreSQL +locks the table to be indexed against writes and performs the entire index build with a single scan of the table\&. Other transactions can still read the table, but if they try to insert, update, or delete rows in the table they will block until the index build is finished\&. This could have a severe effect if the system is a live production database\&. Very large tables can take many hours to be indexed, and even for smaller tables, an index build can lock out writers for periods that are unacceptably long for a production system\&. +.PP +PostgreSQL +supports building indexes without locking out writes\&. This method is invoked by specifying the +CONCURRENTLY +option of +\fBCREATE INDEX\fR\&. When this option is used, +PostgreSQL +must perform two scans of the table, and in addition it must wait for all existing transactions that could potentially modify or use the index to terminate\&. Thus this method requires more total work than a standard index build and takes significantly longer to complete\&. However, since it allows normal operations to continue while the index is built, this method is useful for adding new indexes in a production environment\&. Of course, the extra CPU and I/O load imposed by the index creation might slow other operations\&. +.PP +In a concurrent index build, the index is actually entered as an +\(lqinvalid\(rq +index into the system catalogs in one transaction, then two table scans occur in two more transactions\&. Before each table scan, the index build must wait for existing transactions that have modified the table to terminate\&. After the second scan, the index build must wait for any transactions that have a snapshot (see +Chapter\ \&13) predating the second scan to terminate, including transactions used by any phase of concurrent index builds on other tables, if the indexes involved are partial or have columns that are not simple column references\&. Then finally the index can be marked +\(lqvalid\(rq +and ready for use, and the +\fBCREATE INDEX\fR +command terminates\&. Even then, however, the index may not be immediately usable for queries: in the worst case, it cannot be used as long as transactions exist that predate the start of the index build\&. +.PP +If a problem arises while scanning the table, such as a deadlock or a uniqueness violation in a unique index, the +\fBCREATE INDEX\fR +command will fail but leave behind an +\(lqinvalid\(rq +index\&. This index will be ignored for querying purposes because it might be incomplete; however it will still consume update overhead\&. The +psql +\fB\ed\fR +command will report such an index as +INVALID: +.sp +.if n \{\ +.RS 4 +.\} +.nf +postgres=# \ed tab + Table "public\&.tab" + Column | Type | Collation | Nullable | Default +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\- + col | integer | | | +Indexes: + "idx" btree (col) INVALID +.fi +.if n \{\ +.RE +.\} +.sp +The recommended recovery method in such cases is to drop the index and try again to perform +\fBCREATE INDEX CONCURRENTLY\fR\&. (Another possibility is to rebuild the index with +\fBREINDEX INDEX CONCURRENTLY\fR)\&. +.PP +Another caveat when building a unique index concurrently is that the uniqueness constraint is already being enforced against other transactions when the second table scan begins\&. This means that constraint violations could be reported in other queries prior to the index becoming available for use, or even in cases where the index build eventually fails\&. Also, if a failure does occur in the second scan, the +\(lqinvalid\(rq +index continues to enforce its uniqueness constraint afterwards\&. +.PP +Concurrent builds of expression indexes and partial indexes are supported\&. Errors occurring in the evaluation of these expressions could cause behavior similar to that described above for unique constraint violations\&. +.PP +Regular index builds permit other regular index builds on the same table to occur simultaneously, but only one concurrent index build can occur on a table at a time\&. In either case, schema modification of the table is not allowed while the index is being built\&. Another difference is that a regular +\fBCREATE INDEX\fR +command can be performed within a transaction block, but +\fBCREATE INDEX CONCURRENTLY\fR +cannot\&. +.PP +Concurrent builds for indexes on partitioned tables are currently not supported\&. However, you may concurrently build the index on each partition individually and then finally create the partitioned index non\-concurrently in order to reduce the time where writes to the partitioned table will be locked out\&. In this case, building the partitioned index is a metadata only operation\&. +.SH "NOTES" +.PP +See +Chapter\ \&11 +for information about when indexes can be used, when they are not used, and in which particular situations they can be useful\&. +.PP +Currently, only the B\-tree, GiST, GIN, and BRIN index methods support multiple\-key\-column indexes\&. Whether there can be multiple key columns is independent of whether +INCLUDE +columns can be added to the index\&. Indexes can have up to 32 columns, including +INCLUDE +columns\&. (This limit can be altered when building +PostgreSQL\&.) Only B\-tree currently supports unique indexes\&. +.PP +An +operator class +with optional parameters can be specified for each column of an index\&. The operator class identifies the operators to be used by the index for that column\&. For example, a B\-tree index on four\-byte integers would use the +int4_ops +class; this operator class includes comparison functions for four\-byte integers\&. In practice the default operator class for the column\*(Aqs data type is usually sufficient\&. The main point of having operator classes is that for some data types, there could be more than one meaningful ordering\&. For example, we might want to sort a complex\-number data type either by absolute value or by real part\&. We could do this by defining two operator classes for the data type and then selecting the proper class when creating an index\&. More information about operator classes is in +Section\ \&11.10 +and in +Section\ \&38.16\&. +.PP +When +CREATE INDEX +is invoked on a partitioned table, the default behavior is to recurse to all partitions to ensure they all have matching indexes\&. Each partition is first checked to determine whether an equivalent index already exists, and if so, that index will become attached as a partition index to the index being created, which will become its parent index\&. If no matching index exists, a new index will be created and automatically attached; the name of the new index in each partition will be determined as if no index name had been specified in the command\&. If the +ONLY +option is specified, no recursion is done, and the index is marked invalid\&. (\fBALTER INDEX \&.\&.\&. ATTACH PARTITION\fR +marks the index valid, once all partitions acquire matching indexes\&.) Note, however, that any partition that is created in the future using +\fBCREATE TABLE \&.\&.\&. PARTITION OF\fR +will automatically have a matching index, regardless of whether +ONLY +is specified\&. +.PP +For index methods that support ordered scans (currently, only B\-tree), the optional clauses +ASC, +DESC, +NULLS FIRST, and/or +NULLS LAST +can be specified to modify the sort ordering of the index\&. Since an ordered index can be scanned either forward or backward, it is not normally useful to create a single\-column +DESC +index \(em that sort ordering is already available with a regular index\&. The value of these options is that multicolumn indexes can be created that match the sort ordering requested by a mixed\-ordering query, such as +SELECT \&.\&.\&. ORDER BY x ASC, y DESC\&. The +NULLS +options are useful if you need to support +\(lqnulls sort low\(rq +behavior, rather than the default +\(lqnulls sort high\(rq, in queries that depend on indexes to avoid sorting steps\&. +.PP +The system regularly collects statistics on all of a table\*(Aqs columns\&. Newly\-created non\-expression indexes can immediately use these statistics to determine an index\*(Aqs usefulness\&. For new expression indexes, it is necessary to run +\fBANALYZE\fR +or wait for the +autovacuum daemon +to analyze the table to generate statistics for these indexes\&. +.PP +For most index methods, the speed of creating an index is dependent on the setting of +maintenance_work_mem\&. Larger values will reduce the time needed for index creation, so long as you don\*(Aqt make it larger than the amount of memory really available, which would drive the machine into swapping\&. +.PP +PostgreSQL +can build indexes while leveraging multiple CPUs in order to process the table rows faster\&. This feature is known as +parallel index build\&. For index methods that support building indexes in parallel (currently, only B\-tree), +\fImaintenance_work_mem\fR +specifies the maximum amount of memory that can be used by each index build operation as a whole, regardless of how many worker processes were started\&. Generally, a cost model automatically determines how many worker processes should be requested, if any\&. +.PP +Parallel index builds may benefit from increasing +\fImaintenance_work_mem\fR +where an equivalent serial index build will see little or no benefit\&. Note that +\fImaintenance_work_mem\fR +may influence the number of worker processes requested, since parallel workers must have at least a +32MB +share of the total +\fImaintenance_work_mem\fR +budget\&. There must also be a remaining +32MB +share for the leader process\&. Increasing +max_parallel_maintenance_workers +may allow more workers to be used, which will reduce the time needed for index creation, so long as the index build is not already I/O bound\&. Of course, there should also be sufficient CPU capacity that would otherwise lie idle\&. +.PP +Setting a value for +parallel_workers +via +\fBALTER TABLE\fR +directly controls how many parallel worker processes will be requested by a +\fBCREATE INDEX\fR +against the table\&. This bypasses the cost model completely, and prevents +\fImaintenance_work_mem\fR +from affecting how many parallel workers are requested\&. Setting +parallel_workers +to 0 via +\fBALTER TABLE\fR +will disable parallel index builds on the table in all cases\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +.PP +You might want to reset +parallel_workers +after setting it as part of tuning an index build\&. This avoids inadvertent changes to query plans, since +parallel_workers +affects +\fIall\fR +parallel table scans\&. +.sp .5v +.RE +.PP +While +\fBCREATE INDEX\fR +with the +CONCURRENTLY +option supports parallel builds without special restrictions, only the first table scan is actually performed in parallel\&. +.PP +Use +\fBDROP INDEX\fR +to remove an index\&. +.PP +Like any long\-running transaction, +\fBCREATE INDEX\fR +on a table can affect which tuples can be removed by concurrent +\fBVACUUM\fR +on any other table\&. +.PP +Prior releases of +PostgreSQL +also had an R\-tree index method\&. This method has been removed because it had no significant advantages over the GiST method\&. If +USING rtree +is specified, +\fBCREATE INDEX\fR +will interpret it as +USING gist, to simplify conversion of old databases to GiST\&. +.PP +Each backend running +\fBCREATE INDEX\fR +will report its progress in the +pg_stat_progress_create_index +view\&. See +Section\ \&28.4.2 +for details\&. +.SH "EXAMPLES" +.PP +To create a unique B\-tree index on the column +title +in the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE UNIQUE INDEX title_idx ON films (title); +.fi +.if n \{\ +.RE +.\} +.PP +To create a unique B\-tree index on the column +title +with included columns +director +and +rating +in the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE UNIQUE INDEX title_idx ON films (title) INCLUDE (director, rating); +.fi +.if n \{\ +.RE +.\} +.PP +To create a B\-Tree index with deduplication disabled: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX title_idx ON films (title) WITH (deduplicate_items = off); +.fi +.if n \{\ +.RE +.\} +.PP +To create an index on the expression +lower(title), allowing efficient case\-insensitive searches: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX ON films ((lower(title))); +.fi +.if n \{\ +.RE +.\} +.sp +(In this example we have chosen to omit the index name, so the system will choose a name, typically +films_lower_idx\&.) +.PP +To create an index with non\-default collation: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX title_idx_german ON films (title COLLATE "de_DE"); +.fi +.if n \{\ +.RE +.\} +.PP +To create an index with non\-default sort ordering of nulls: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX title_idx_nulls_low ON films (title NULLS FIRST); +.fi +.if n \{\ +.RE +.\} +.PP +To create an index with non\-default fill factor: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70); +.fi +.if n \{\ +.RE +.\} +.PP +To create a +GIN +index with fast updates disabled: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX gin_idx ON documents_table USING GIN (locations) WITH (fastupdate = off); +.fi +.if n \{\ +.RE +.\} +.PP +To create an index on the column +code +in the table +films +and have the index reside in the tablespace +indexspace: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX code_idx ON films (code) TABLESPACE indexspace; +.fi +.if n \{\ +.RE +.\} +.PP +To create a GiST index on a point attribute so that we can efficiently use box operators on the result of the conversion function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX pointloc + ON points USING gist (box(location,location)); +SELECT * FROM points + WHERE box(location,location) && \*(Aq(0,0),(1,1)\*(Aq::box; +.fi +.if n \{\ +.RE +.\} +.PP +To create an index without locking out writes to the table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE INDEX CONCURRENTLY sales_quantity_index ON sales_table (quantity); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE INDEX\fR +is a +PostgreSQL +language extension\&. There are no provisions for indexes in the SQL standard\&. +.SH "SEE ALSO" +ALTER INDEX (\fBALTER_INDEX\fR(7)), DROP INDEX (\fBDROP_INDEX\fR(7)), \fBREINDEX\fR(7), Section\ \&28.4.2 diff --git a/doc/src/sgml/man7/CREATE_LANGUAGE.7 b/doc/src/sgml/man7/CREATE_LANGUAGE.7 new file mode 100644 index 0000000..ac45c43 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_LANGUAGE.7 @@ -0,0 +1,178 @@ +'\" t +.\" Title: CREATE LANGUAGE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE LANGUAGE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_LANGUAGE \- define a new procedural language +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE \fIname\fR + HANDLER \fIcall_handler\fR [ INLINE \fIinline_handler\fR ] [ VALIDATOR \fIvalfunction\fR ] +CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE \fIname\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE LANGUAGE\fR +registers a new procedural language with a +PostgreSQL +database\&. Subsequently, functions and procedures can be defined in this new language\&. +.PP +\fBCREATE LANGUAGE\fR +effectively associates the language name with handler function(s) that are responsible for executing functions written in the language\&. Refer to +Chapter\ \&58 +for more information about language handlers\&. +.PP +\fBCREATE OR REPLACE LANGUAGE\fR +will either create a new language, or replace an existing definition\&. If the language already exists, its parameters are updated according to the command, but the language\*(Aqs ownership and permissions settings do not change, and any existing functions written in the language are assumed to still be valid\&. +.PP +One must have the +PostgreSQL +superuser privilege to register a new language or change an existing language\*(Aqs parameters\&. However, once the language is created it is valid to assign ownership of it to a non\-superuser, who may then drop it, change its permissions, rename it, or assign it to a new owner\&. (Do not, however, assign ownership of the underlying C functions to a non\-superuser; that would create a privilege escalation path for that user\&.) +.PP +The form of +\fBCREATE LANGUAGE\fR +that does not supply any handler function is obsolete\&. For backwards compatibility with old dump files, it is interpreted as +\fBCREATE EXTENSION\fR\&. That will work if the language has been packaged into an extension of the same name, which is the conventional way to set up procedural languages\&. +.SH "PARAMETERS" +.PP +TRUSTED +.RS 4 +TRUSTED +specifies that the language does not grant access to data that the user would not otherwise have\&. If this key word is omitted when registering the language, only users with the +PostgreSQL +superuser privilege can use this language to create new functions\&. +.RE +.PP +PROCEDURAL +.RS 4 +This is a noise word\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the new procedural language\&. The name must be unique among the languages in the database\&. +.RE +.PP +HANDLER \fIcall_handler\fR +.RS 4 +\fIcall_handler\fR +is the name of a previously registered function that will be called to execute the procedural language\*(Aqs functions\&. The call handler for a procedural language must be written in a compiled language such as C with version 1 call convention and registered with +PostgreSQL +as a function taking no arguments and returning the +language_handler +type, a placeholder type that is simply used to identify the function as a call handler\&. +.RE +.PP +INLINE \fIinline_handler\fR +.RS 4 +\fIinline_handler\fR +is the name of a previously registered function that will be called to execute an anonymous code block (\fBDO\fR +command) in this language\&. If no +\fIinline_handler\fR +function is specified, the language does not support anonymous code blocks\&. The handler function must take one argument of type +internal, which will be the +\fBDO\fR +command\*(Aqs internal representation, and it will typically return +void\&. The return value of the handler is ignored\&. +.RE +.PP +VALIDATOR \fIvalfunction\fR +.RS 4 +\fIvalfunction\fR +is the name of a previously registered function that will be called when a new function in the language is created, to validate the new function\&. If no validator function is specified, then a new function will not be checked when it is created\&. The validator function must take one argument of type +oid, which will be the OID of the to\-be\-created function, and will typically return +void\&. +.sp +A validator function would typically inspect the function body for syntactical correctness, but it can also look at other properties of the function, for example if the language cannot handle certain argument types\&. To signal an error, the validator function should use the +\fBereport()\fR +function\&. The return value of the function is ignored\&. +.RE +.SH "NOTES" +.PP +Use +\fBDROP LANGUAGE\fR +to drop procedural languages\&. +.PP +The system catalog +pg_language +(see +Section\ \&53.29) records information about the currently installed languages\&. Also, the +psql +command +\fB\edL\fR +lists the installed languages\&. +.PP +To create functions in a procedural language, a user must have the +USAGE +privilege for the language\&. By default, +USAGE +is granted to +PUBLIC +(i\&.e\&., everyone) for trusted languages\&. This can be revoked if desired\&. +.PP +Procedural languages are local to individual databases\&. However, a language can be installed into the +template1 +database, which will cause it to be available automatically in all subsequently\-created databases\&. +.SH "EXAMPLES" +.PP +A minimal sequence for creating a new procedural language is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION plsample_call_handler() RETURNS language_handler + AS \*(Aq$libdir/plsample\*(Aq + LANGUAGE C; +CREATE LANGUAGE plsample + HANDLER plsample_call_handler; +.fi +.if n \{\ +.RE +.\} +.sp +Typically that would be written in an extension\*(Aqs creation script, and users would do this to install the extension: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE EXTENSION plsample; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE LANGUAGE\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER LANGUAGE (\fBALTER_LANGUAGE\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP LANGUAGE (\fBDROP_LANGUAGE\fR(7)), \fBGRANT\fR(7), \fBREVOKE\fR(7) diff --git a/doc/src/sgml/man7/CREATE_MATERIALIZED_VIEW.7 b/doc/src/sgml/man7/CREATE_MATERIALIZED_VIEW.7 new file mode 100644 index 0000000..2ac8bb9 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_MATERIALIZED_VIEW.7 @@ -0,0 +1,131 @@ +'\" t +.\" Title: CREATE MATERIALIZED VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE MATERIALIZED VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_MATERIALIZED_VIEW \- define a new materialized view +.SH "SYNOPSIS" +.sp +.nf +CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] \fItable_name\fR + [ (\fIcolumn_name\fR [, \&.\&.\&.] ) ] + [ USING \fImethod\fR ] + [ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] + [ TABLESPACE \fItablespace_name\fR ] + AS \fIquery\fR + [ WITH [ NO ] DATA ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE MATERIALIZED VIEW\fR +defines a materialized view of a query\&. The query is executed and used to populate the view at the time the command is issued (unless +\fBWITH NO DATA\fR +is used) and may be refreshed later using +\fBREFRESH MATERIALIZED VIEW\fR\&. +.PP +\fBCREATE MATERIALIZED VIEW\fR +is similar to +\fBCREATE TABLE AS\fR, except that it also remembers the query used to initialize the view, so that it can be refreshed later upon demand\&. A materialized view has many of the same properties as a table, but there is no support for temporary materialized views\&. +.PP +\fBCREATE MATERIALIZED VIEW\fR +requires +CREATE +privilege on the schema used for the materialized view\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a materialized view with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing materialized view is anything like the one that would have been created\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the materialized view to be created\&. The name must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column in the new materialized view\&. If column names are not provided, they are taken from the output column names of the query\&. +.RE +.PP +USING \fImethod\fR +.RS 4 +This optional clause specifies the table access method to use to store the contents for the new materialized view; the method needs be an access method of type +TABLE\&. See +Chapter\ \&63 +for more information\&. If this option is not specified, the default table access method is chosen for the new materialized view\&. See +default_table_access_method +for more information\&. +.RE +.PP +WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause specifies optional storage parameters for the new materialized view; see +Storage Parameters +in the +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +documentation for more information\&. All parameters supported for +CREATE TABLE +are also supported for +CREATE MATERIALIZED VIEW\&. See +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for more information\&. +.RE +.PP +TABLESPACE \fItablespace_name\fR +.RS 4 +The +\fItablespace_name\fR +is the name of the tablespace in which the new materialized view is to be created\&. If not specified, +default_tablespace +is consulted\&. +.RE +.PP +\fIquery\fR +.RS 4 +A +\fBSELECT\fR, +\fBTABLE\fR, or +\fBVALUES\fR +command\&. This query will run within a security\-restricted operation; in particular, calls to functions that themselves create temporary tables will fail\&. +.RE +.PP +WITH [ NO ] DATA +.RS 4 +This clause specifies whether or not the materialized view should be populated at creation time\&. If not, the materialized view will be flagged as unscannable and cannot be queried until +\fBREFRESH MATERIALIZED VIEW\fR +is used\&. +.RE +.SH "COMPATIBILITY" +.PP +\fBCREATE MATERIALIZED VIEW\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER MATERIALIZED VIEW (\fBALTER_MATERIALIZED_VIEW\fR(7)), CREATE TABLE AS (\fBCREATE_TABLE_AS\fR(7)), CREATE VIEW (\fBCREATE_VIEW\fR(7)), DROP MATERIALIZED VIEW (\fBDROP_MATERIALIZED_VIEW\fR(7)), REFRESH MATERIALIZED VIEW (\fBREFRESH_MATERIALIZED_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_OPERATOR.7 b/doc/src/sgml/man7/CREATE_OPERATOR.7 new file mode 100644 index 0000000..235f688 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_OPERATOR.7 @@ -0,0 +1,282 @@ +'\" t +.\" Title: CREATE OPERATOR +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE OPERATOR" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_OPERATOR \- define a new operator +.SH "SYNOPSIS" +.sp +.nf +CREATE OPERATOR \fIname\fR ( + {FUNCTION|PROCEDURE} = \fIfunction_name\fR + [, LEFTARG = \fIleft_type\fR ] [, RIGHTARG = \fIright_type\fR ] + [, COMMUTATOR = \fIcom_op\fR ] [, NEGATOR = \fIneg_op\fR ] + [, RESTRICT = \fIres_proc\fR ] [, JOIN = \fIjoin_proc\fR ] + [, HASHES ] [, MERGES ] +) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE OPERATOR\fR +defines a new operator, +\fIname\fR\&. The user who defines an operator becomes its owner\&. If a schema name is given then the operator is created in the specified schema\&. Otherwise it is created in the current schema\&. +.PP +The operator name is a sequence of up to +NAMEDATALEN\-1 (63 by default) characters from the following list: +.sp +.if n \{\ +.RS 4 +.\} +.nf ++ \- * / < > = ~ ! @ # % ^ & | ` ? +.fi +.if n \{\ +.RE +.\} +.sp +There are a few restrictions on your choice of name: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\-\- +and +/* +cannot appear anywhere in an operator name, since they will be taken as the start of a comment\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A multicharacter operator name cannot end in ++ +or +\-, unless the name also contains at least one of these characters: +.sp +.if n \{\ +.RS 4 +.\} +.nf +~ ! @ # % ^ & | ` ? +.fi +.if n \{\ +.RE +.\} +.sp +For example, +@\- +is an allowed operator name, but +*\- +is not\&. This restriction allows +PostgreSQL +to parse SQL\-compliant commands without requiring spaces between tokens\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The symbol +=> +is reserved by the SQL grammar, so it cannot be used as an operator name\&. +.RE +.PP +The operator +!= +is mapped to +<> +on input, so these two names are always equivalent\&. +.PP +For binary operators, both +LEFTARG +and +RIGHTARG +must be defined\&. For prefix operators only +RIGHTARG +should be defined\&. The +\fIfunction_name\fR +function must have been previously defined using +\fBCREATE FUNCTION\fR +and must be defined to accept the correct number of arguments (either one or two) of the indicated types\&. +.PP +In the syntax of +CREATE OPERATOR, the keywords +FUNCTION +and +PROCEDURE +are equivalent, but the referenced function must in any case be a function, not a procedure\&. The use of the keyword +PROCEDURE +here is historical and deprecated\&. +.PP +The other clauses specify optional operator optimization clauses\&. Their meaning is detailed in +Section\ \&38.15\&. +.PP +To be able to create an operator, you must have +USAGE +privilege on the argument types and the return type, as well as +EXECUTE +privilege on the underlying function\&. If a commutator or negator operator is specified, you must own these operators\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the operator to be defined\&. See above for allowable characters\&. The name can be schema\-qualified, for example +CREATE OPERATOR myschema\&.+ (\&.\&.\&.)\&. If not, then the operator is created in the current schema\&. Two operators in the same schema can have the same name if they operate on different data types\&. This is called +overloading\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +The function used to implement this operator\&. +.RE +.PP +\fIleft_type\fR +.RS 4 +The data type of the operator\*(Aqs left operand, if any\&. This option would be omitted for a prefix operator\&. +.RE +.PP +\fIright_type\fR +.RS 4 +The data type of the operator\*(Aqs right operand\&. +.RE +.PP +\fIcom_op\fR +.RS 4 +The commutator of this operator\&. +.RE +.PP +\fIneg_op\fR +.RS 4 +The negator of this operator\&. +.RE +.PP +\fIres_proc\fR +.RS 4 +The restriction selectivity estimator function for this operator\&. +.RE +.PP +\fIjoin_proc\fR +.RS 4 +The join selectivity estimator function for this operator\&. +.RE +.PP +HASHES +.RS 4 +Indicates this operator can support a hash join\&. +.RE +.PP +MERGES +.RS 4 +Indicates this operator can support a merge join\&. +.RE +.PP +To give a schema\-qualified operator name in +\fIcom_op\fR +or the other optional arguments, use the +OPERATOR() +syntax, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +COMMUTATOR = OPERATOR(myschema\&.===) , +.fi +.if n \{\ +.RE +.\} +.SH "NOTES" +.PP +Refer to +Section\ \&38.14 +for further information\&. +.PP +It is not possible to specify an operator\*(Aqs lexical precedence in +\fBCREATE OPERATOR\fR, because the parser\*(Aqs precedence behavior is hard\-wired\&. See +Section\ \&4.1.6 +for precedence details\&. +.PP +The obsolete options +SORT1, +SORT2, +LTCMP, and +GTCMP +were formerly used to specify the names of sort operators associated with a merge\-joinable operator\&. This is no longer necessary, since information about associated operators is found by looking at B\-tree operator families instead\&. If one of these options is given, it is ignored except for implicitly setting +MERGES +true\&. +.PP +Use +\fBDROP OPERATOR\fR +to delete user\-defined operators from a database\&. Use +\fBALTER OPERATOR\fR +to modify operators in a database\&. +.SH "EXAMPLES" +.PP +The following command defines a new operator, area\-equality, for the data type +box: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE OPERATOR === ( + LEFTARG = box, + RIGHTARG = box, + FUNCTION = area_equal_function, + COMMUTATOR = ===, + NEGATOR = !==, + RESTRICT = area_restriction_function, + JOIN = area_join_function, + HASHES, MERGES +); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE OPERATOR\fR +is a +PostgreSQL +extension\&. There are no provisions for user\-defined operators in the SQL standard\&. +.SH "SEE ALSO" +ALTER OPERATOR (\fBALTER_OPERATOR\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), DROP OPERATOR (\fBDROP_OPERATOR\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_OPERATOR_CLASS.7 b/doc/src/sgml/man7/CREATE_OPERATOR_CLASS.7 new file mode 100644 index 0000000..d0b9b3d --- /dev/null +++ b/doc/src/sgml/man7/CREATE_OPERATOR_CLASS.7 @@ -0,0 +1,223 @@ +'\" t +.\" Title: CREATE OPERATOR CLASS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE OPERATOR CLASS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_OPERATOR_CLASS \- define a new operator class +.SH "SYNOPSIS" +.sp +.nf +CREATE OPERATOR CLASS \fIname\fR [ DEFAULT ] FOR TYPE \fIdata_type\fR + USING \fIindex_method\fR [ FAMILY \fIfamily_name\fR ] AS + { OPERATOR \fIstrategy_number\fR \fIoperator_name\fR [ ( \fIop_type\fR, \fIop_type\fR ) ] [ FOR SEARCH | FOR ORDER BY \fIsort_family_name\fR ] + | FUNCTION \fIsupport_number\fR [ ( \fIop_type\fR [ , \fIop_type\fR ] ) ] \fIfunction_name\fR ( \fIargument_type\fR [, \&.\&.\&.] ) + | STORAGE \fIstorage_type\fR + } [, \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE OPERATOR CLASS\fR +creates a new operator class\&. An operator class defines how a particular data type can be used with an index\&. The operator class specifies that certain operators will fill particular roles or +\(lqstrategies\(rq +for this data type and this index method\&. The operator class also specifies the support functions to be used by the index method when the operator class is selected for an index column\&. All the operators and functions used by an operator class must be defined before the operator class can be created\&. +.PP +If a schema name is given then the operator class is created in the specified schema\&. Otherwise it is created in the current schema\&. Two operator classes in the same schema can have the same name only if they are for different index methods\&. +.PP +The user who defines an operator class becomes its owner\&. Presently, the creating user must be a superuser\&. (This restriction is made because an erroneous operator class definition could confuse or even crash the server\&.) +.PP +\fBCREATE OPERATOR CLASS\fR +does not presently check whether the operator class definition includes all the operators and functions required by the index method, nor whether the operators and functions form a self\-consistent set\&. It is the user\*(Aqs responsibility to define a valid operator class\&. +.PP +Related operator classes can be grouped into +operator families\&. To add a new operator class to an existing family, specify the +FAMILY +option in +\fBCREATE OPERATOR CLASS\fR\&. Without this option, the new class is placed into a family named the same as the new class (creating that family if it doesn\*(Aqt already exist)\&. +.PP +Refer to +Section\ \&38.16 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the operator class to be created\&. The name can be schema\-qualified\&. +.RE +.PP +DEFAULT +.RS 4 +If present, the operator class will become the default operator class for its data type\&. At most one operator class can be the default for a specific data type and index method\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The column data type that this operator class is for\&. +.RE +.PP +\fIindex_method\fR +.RS 4 +The name of the index method this operator class is for\&. +.RE +.PP +\fIfamily_name\fR +.RS 4 +The name of the existing operator family to add this operator class to\&. If not specified, a family named the same as the operator class is used (creating it, if it doesn\*(Aqt already exist)\&. +.RE +.PP +\fIstrategy_number\fR +.RS 4 +The index method\*(Aqs strategy number for an operator associated with the operator class\&. +.RE +.PP +\fIoperator_name\fR +.RS 4 +The name (optionally schema\-qualified) of an operator associated with the operator class\&. +.RE +.PP +\fIop_type\fR +.RS 4 +In an +OPERATOR +clause, the operand data type(s) of the operator, or +NONE +to signify a prefix operator\&. The operand data types can be omitted in the normal case where they are the same as the operator class\*(Aqs data type\&. +.sp +In a +FUNCTION +clause, the operand data type(s) the function is intended to support, if different from the input data type(s) of the function (for B\-tree comparison functions and hash functions) or the class\*(Aqs data type (for B\-tree sort support functions, B\-tree equal image functions, and all functions in GiST, SP\-GiST, GIN and BRIN operator classes)\&. These defaults are correct, and so +\fIop_type\fR +need not be specified in +FUNCTION +clauses, except for the case of a B\-tree sort support function that is meant to support cross\-data\-type comparisons\&. +.RE +.PP +\fIsort_family_name\fR +.RS 4 +The name (optionally schema\-qualified) of an existing +btree +operator family that describes the sort ordering associated with an ordering operator\&. +.sp +If neither +FOR SEARCH +nor +FOR ORDER BY +is specified, +FOR SEARCH +is the default\&. +.RE +.PP +\fIsupport_number\fR +.RS 4 +The index method\*(Aqs support function number for a function associated with the operator class\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +The name (optionally schema\-qualified) of a function that is an index method support function for the operator class\&. +.RE +.PP +\fIargument_type\fR +.RS 4 +The parameter data type(s) of the function\&. +.RE +.PP +\fIstorage_type\fR +.RS 4 +The data type actually stored in the index\&. Normally this is the same as the column data type, but some index methods (currently GiST, GIN, SP\-GiST and BRIN) allow it to be different\&. The +STORAGE +clause must be omitted unless the index method allows a different type to be used\&. If the column +\fIdata_type\fR +is specified as +anyarray, the +\fIstorage_type\fR +can be declared as +anyelement +to indicate that the index entries are members of the element type belonging to the actual array type that each particular index is created for\&. +.RE +.PP +The +OPERATOR, +FUNCTION, and +STORAGE +clauses can appear in any order\&. +.SH "NOTES" +.PP +Because the index machinery does not check access permissions on functions before using them, including a function or operator in an operator class is tantamount to granting public execute permission on it\&. This is usually not an issue for the sorts of functions that are useful in an operator class\&. +.PP +The operators should not be defined by SQL functions\&. An SQL function is likely to be inlined into the calling query, which will prevent the optimizer from recognizing that the query matches an index\&. +.PP +Before +PostgreSQL +8\&.4, the +OPERATOR +clause could include a +RECHECK +option\&. This is no longer supported because whether an index operator is +\(lqlossy\(rq +is now determined on\-the\-fly at run time\&. This allows efficient handling of cases where an operator might or might not be lossy\&. +.SH "EXAMPLES" +.PP +The following example command defines a GiST index operator class for the data type +_int4 +(array of +int4)\&. See the +intarray +module for the complete example\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE OPERATOR CLASS gist__int_ops + DEFAULT FOR TYPE _int4 USING gist AS + OPERATOR 3 &&, + OPERATOR 6 = (anyarray, anyarray), + OPERATOR 7 @>, + OPERATOR 8 <@, + OPERATOR 20 @@ (_int4, query_int), + FUNCTION 1 g_int_consistent (internal, _int4, smallint, oid, internal), + FUNCTION 2 g_int_union (internal, internal), + FUNCTION 3 g_int_compress (internal), + FUNCTION 4 g_int_decompress (internal), + FUNCTION 5 g_int_penalty (internal, internal, internal), + FUNCTION 6 g_int_picksplit (internal, internal), + FUNCTION 7 g_int_same (_int4, _int4, internal); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE OPERATOR CLASS\fR +is a +PostgreSQL +extension\&. There is no +\fBCREATE OPERATOR CLASS\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER OPERATOR CLASS (\fBALTER_OPERATOR_CLASS\fR(7)), DROP OPERATOR CLASS (\fBDROP_OPERATOR_CLASS\fR(7)), CREATE OPERATOR FAMILY (\fBCREATE_OPERATOR_FAMILY\fR(7)), ALTER OPERATOR FAMILY (\fBALTER_OPERATOR_FAMILY\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_OPERATOR_FAMILY.7 b/doc/src/sgml/man7/CREATE_OPERATOR_FAMILY.7 new file mode 100644 index 0000000..af6e5f7 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_OPERATOR_FAMILY.7 @@ -0,0 +1,79 @@ +'\" t +.\" Title: CREATE OPERATOR FAMILY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE OPERATOR FAMILY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_OPERATOR_FAMILY \- define a new operator family +.SH "SYNOPSIS" +.sp +.nf +CREATE OPERATOR FAMILY \fIname\fR USING \fIindex_method\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE OPERATOR FAMILY\fR +creates a new operator family\&. An operator family defines a collection of related operator classes, and perhaps some additional operators and support functions that are compatible with these operator classes but not essential for the functioning of any individual index\&. (Operators and functions that are essential to indexes should be grouped within the relevant operator class, rather than being +\(lqloose\(rq +in the operator family\&. Typically, single\-data\-type operators are bound to operator classes, while cross\-data\-type operators can be loose in an operator family containing operator classes for both data types\&.) +.PP +The new operator family is initially empty\&. It should be populated by issuing subsequent +\fBCREATE OPERATOR CLASS\fR +commands to add contained operator classes, and optionally +\fBALTER OPERATOR FAMILY\fR +commands to add +\(lqloose\(rq +operators and their corresponding support functions\&. +.PP +If a schema name is given then the operator family is created in the specified schema\&. Otherwise it is created in the current schema\&. Two operator families in the same schema can have the same name only if they are for different index methods\&. +.PP +The user who defines an operator family becomes its owner\&. Presently, the creating user must be a superuser\&. (This restriction is made because an erroneous operator family definition could confuse or even crash the server\&.) +.PP +Refer to +Section\ \&38.16 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the operator family to be created\&. The name can be schema\-qualified\&. +.RE +.PP +\fIindex_method\fR +.RS 4 +The name of the index method this operator family is for\&. +.RE +.SH "COMPATIBILITY" +.PP +\fBCREATE OPERATOR FAMILY\fR +is a +PostgreSQL +extension\&. There is no +\fBCREATE OPERATOR FAMILY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER OPERATOR FAMILY (\fBALTER_OPERATOR_FAMILY\fR(7)), DROP OPERATOR FAMILY (\fBDROP_OPERATOR_FAMILY\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), ALTER OPERATOR CLASS (\fBALTER_OPERATOR_CLASS\fR(7)), DROP OPERATOR CLASS (\fBDROP_OPERATOR_CLASS\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_POLICY.7 b/doc/src/sgml/man7/CREATE_POLICY.7 new file mode 100644 index 0000000..af93bbf --- /dev/null +++ b/doc/src/sgml/man7/CREATE_POLICY.7 @@ -0,0 +1,655 @@ +'\" t +.\" Title: CREATE POLICY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE POLICY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_POLICY \- define a new row\-level security policy for a table +.SH "SYNOPSIS" +.sp +.nf +CREATE POLICY \fIname\fR ON \fItable_name\fR + [ AS { PERMISSIVE | RESTRICTIVE } ] + [ FOR { ALL | SELECT | INSERT | UPDATE | DELETE } ] + [ TO { \fIrole_name\fR | PUBLIC | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, \&.\&.\&.] ] + [ USING ( \fIusing_expression\fR ) ] + [ WITH CHECK ( \fIcheck_expression\fR ) ] +.fi +.SH "DESCRIPTION" +.PP +The +\fBCREATE POLICY\fR +command defines a new row\-level security policy for a table\&. Note that row\-level security must be enabled on the table (using +\fBALTER TABLE \&.\&.\&. ENABLE ROW LEVEL SECURITY\fR) in order for created policies to be applied\&. +.PP +A policy grants the permission to select, insert, update, or delete rows that match the relevant policy expression\&. Existing table rows are checked against the expression specified in +USING, while new rows that would be created via +INSERT +or +UPDATE +are checked against the expression specified in +WITH CHECK\&. When a +USING +expression returns true for a given row then that row is visible to the user, while if false or null is returned then the row is not visible\&. When a +WITH CHECK +expression returns true for a row then that row is inserted or updated, while if false or null is returned then an error occurs\&. +.PP +For +\fBINSERT\fR, +\fBUPDATE\fR, and +\fBMERGE\fR +statements, +WITH CHECK +expressions are enforced after +BEFORE +triggers are fired, and before any actual data modifications are made\&. Thus a +BEFORE ROW +trigger may modify the data to be inserted, affecting the result of the security policy check\&. +WITH CHECK +expressions are enforced before any other constraints\&. +.PP +Policy names are per\-table\&. Therefore, one policy name can be used for many different tables and have a definition for each table which is appropriate to that table\&. +.PP +Policies can be applied for specific commands or for specific roles\&. The default for newly created policies is that they apply for all commands and roles, unless otherwise specified\&. Multiple policies may apply to a single command; see below for more details\&. +Table\ \&287 +summarizes how the different types of policy apply to specific commands\&. +.PP +For policies that can have both +USING +and +WITH CHECK +expressions (ALL +and +UPDATE), if no +WITH CHECK +expression is defined, then the +USING +expression will be used both to determine which rows are visible (normal +USING +case) and which new rows will be allowed to be added (WITH CHECK +case)\&. +.PP +If row\-level security is enabled for a table, but no applicable policies exist, a +\(lqdefault deny\(rq +policy is assumed, so that no rows will be visible or updatable\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the policy to be created\&. This must be distinct from the name of any other policy for the table\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table the policy applies to\&. +.RE +.PP +PERMISSIVE +.RS 4 +Specify that the policy is to be created as a permissive policy\&. All permissive policies which are applicable to a given query will be combined together using the Boolean +\(lqOR\(rq +operator\&. By creating permissive policies, administrators can add to the set of records which can be accessed\&. Policies are permissive by default\&. +.RE +.PP +RESTRICTIVE +.RS 4 +Specify that the policy is to be created as a restrictive policy\&. All restrictive policies which are applicable to a given query will be combined together using the Boolean +\(lqAND\(rq +operator\&. By creating restrictive policies, administrators can reduce the set of records which can be accessed as all restrictive policies must be passed for each record\&. +.sp +Note that there needs to be at least one permissive policy to grant access to records before restrictive policies can be usefully used to reduce that access\&. If only restrictive policies exist, then no records will be accessible\&. When a mix of permissive and restrictive policies are present, a record is only accessible if at least one of the permissive policies passes, in addition to all the restrictive policies\&. +.RE +.PP +\fIcommand\fR +.RS 4 +The command to which the policy applies\&. Valid options are +\fBALL\fR, +\fBSELECT\fR, +\fBINSERT\fR, +\fBUPDATE\fR, and +\fBDELETE\fR\&. +\fBALL\fR +is the default\&. See below for specifics regarding how these are applied\&. +.RE +.PP +\fIrole_name\fR +.RS 4 +The role(s) to which the policy is to be applied\&. The default is +PUBLIC, which will apply the policy to all roles\&. +.RE +.PP +\fIusing_expression\fR +.RS 4 +Any +SQL +conditional expression (returning +boolean)\&. The conditional expression cannot contain any aggregate or window functions\&. This expression will be added to queries that refer to the table if row\-level security is enabled\&. Rows for which the expression returns true will be visible\&. Any rows for which the expression returns false or null will not be visible to the user (in a +\fBSELECT\fR), and will not be available for modification (in an +\fBUPDATE\fR +or +\fBDELETE\fR)\&. Such rows are silently suppressed; no error is reported\&. +.RE +.PP +\fIcheck_expression\fR +.RS 4 +Any +SQL +conditional expression (returning +boolean)\&. The conditional expression cannot contain any aggregate or window functions\&. This expression will be used in +\fBINSERT\fR +and +\fBUPDATE\fR +queries against the table if row\-level security is enabled\&. Only rows for which the expression evaluates to true will be allowed\&. An error will be thrown if the expression evaluates to false or null for any of the records inserted or any of the records that result from the update\&. Note that the +\fIcheck_expression\fR +is evaluated against the proposed new contents of the row, not the original contents\&. +.RE +.SS "Per\-Command Policies" +.PP +ALL +.RS 4 +Using +ALL +for a policy means that it will apply to all commands, regardless of the type of command\&. If an +ALL +policy exists and more specific policies exist, then both the +ALL +policy and the more specific policy (or policies) will be applied\&. Additionally, +ALL +policies will be applied to both the selection side of a query and the modification side, using the +USING +expression for both cases if only a +USING +expression has been defined\&. +.sp +As an example, if an +UPDATE +is issued, then the +ALL +policy will be applicable both to what the +UPDATE +will be able to select as rows to be updated (applying the +USING +expression), and to the resulting updated rows, to check if they are permitted to be added to the table (applying the +WITH CHECK +expression, if defined, and the +USING +expression otherwise)\&. If an +\fBINSERT\fR +or +\fBUPDATE\fR +command attempts to add rows to the table that do not pass the +ALL +policy\*(Aqs +WITH CHECK +expression, the entire command will be aborted\&. +.RE +.PP +SELECT +.RS 4 +Using +SELECT +for a policy means that it will apply to +SELECT +queries and whenever +SELECT +permissions are required on the relation the policy is defined for\&. The result is that only those records from the relation that pass the +SELECT +policy will be returned during a +SELECT +query, and that queries that require +SELECT +permissions, such as +UPDATE, will also only see those records that are allowed by the +SELECT +policy\&. A +SELECT +policy cannot have a +WITH CHECK +expression, as it only applies in cases where records are being retrieved from the relation\&. +.RE +.PP +INSERT +.RS 4 +Using +INSERT +for a policy means that it will apply to +INSERT +commands and +MERGE +commands that contain +INSERT +actions\&. Rows being inserted that do not pass this policy will result in a policy violation error, and the entire +INSERT +command will be aborted\&. An +INSERT +policy cannot have a +USING +expression, as it only applies in cases where records are being added to the relation\&. +.sp +Note that +INSERT +with +ON CONFLICT DO UPDATE +checks +INSERT +policies\*(Aq +WITH CHECK +expressions only for rows appended to the relation by the +INSERT +path\&. +.RE +.PP +UPDATE +.RS 4 +Using +UPDATE +for a policy means that it will apply to +UPDATE, +SELECT FOR UPDATE +and +SELECT FOR SHARE +commands, as well as auxiliary +ON CONFLICT DO UPDATE +clauses of +INSERT +commands\&. +MERGE +commands containing +UPDATE +actions are affected as well\&. Since +UPDATE +involves pulling an existing record and replacing it with a new modified record, +UPDATE +policies accept both a +USING +expression and a +WITH CHECK +expression\&. The +USING +expression determines which records the +UPDATE +command will see to operate against, while the +WITH CHECK +expression defines which modified rows are allowed to be stored back into the relation\&. +.sp +Any rows whose updated values do not pass the +WITH CHECK +expression will cause an error, and the entire command will be aborted\&. If only a +USING +clause is specified, then that clause will be used for both +USING +and +WITH CHECK +cases\&. +.sp +Typically an +UPDATE +command also needs to read data from columns in the relation being updated (e\&.g\&., in a +WHERE +clause or a +RETURNING +clause, or in an expression on the right hand side of the +SET +clause)\&. In this case, +SELECT +rights are also required on the relation being updated, and the appropriate +SELECT +or +ALL +policies will be applied in addition to the +UPDATE +policies\&. Thus the user must have access to the row(s) being updated through a +SELECT +or +ALL +policy in addition to being granted permission to update the row(s) via an +UPDATE +or +ALL +policy\&. +.sp +When an +INSERT +command has an auxiliary +ON CONFLICT DO UPDATE +clause, if the +UPDATE +path is taken, the row to be updated is first checked against the +USING +expressions of any +UPDATE +policies, and then the new updated row is checked against the +WITH CHECK +expressions\&. Note, however, that unlike a standalone +UPDATE +command, if the existing row does not pass the +USING +expressions, an error will be thrown (the +UPDATE +path will +\fInever\fR +be silently avoided)\&. +.RE +.PP +DELETE +.RS 4 +Using +DELETE +for a policy means that it will apply to +DELETE +commands\&. Only rows that pass this policy will be seen by a +DELETE +command\&. There can be rows that are visible through a +SELECT +that are not available for deletion, if they do not pass the +USING +expression for the +DELETE +policy\&. +.sp +In most cases a +DELETE +command also needs to read data from columns in the relation that it is deleting from (e\&.g\&., in a +WHERE +clause or a +RETURNING +clause)\&. In this case, +SELECT +rights are also required on the relation, and the appropriate +SELECT +or +ALL +policies will be applied in addition to the +DELETE +policies\&. Thus the user must have access to the row(s) being deleted through a +SELECT +or +ALL +policy in addition to being granted permission to delete the row(s) via a +DELETE +or +ALL +policy\&. +.sp +A +DELETE +policy cannot have a +WITH CHECK +expression, as it only applies in cases where records are being deleted from the relation, so that there is no new row to check\&. +.RE +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&287.\ \&Policies Applied by Command Type +.TS +allbox tab(:); +lB lB lB lB s lB +^ lB lB lB lB lB. +T{ +Command +T}:T{ +SELECT/ALL policy +T}:T{ +INSERT/ALL policy +T}:T{ +UPDATE/ALL policy +T}:T{ +DELETE/ALL policy +T} +:T{ +USING expression +T}:T{ +WITH CHECK expression +T}:T{ +USING expression +T}:T{ +WITH CHECK expression +T}:T{ +USING expression +T} +.T& +l l l l l l +l l l l l l +l l l l l l +l l l l l l +l l l l l l +l l l l l l +l l l l l l +l s s s s s. +T{ +\fBSELECT\fR +T}:T{ +Existing row +T}:T{ +\(em +T}:T{ +\(em +T}:T{ +\(em +T}:T{ +\(em +T} +T{ +\fBSELECT FOR UPDATE/SHARE\fR +T}:T{ +Existing row +T}:T{ +\(em +T}:T{ +Existing row +T}:T{ +\(em +T}:T{ +\(em +T} +T{ +\fBINSERT\fR / \fBMERGE \&.\&.\&. THEN INSERT\fR +T}:T{ +\(em +T}:T{ +New row +T}:T{ +\(em +T}:T{ +\(em +T}:T{ +\(em +T} +T{ +\fBINSERT \&.\&.\&. RETURNING\fR +T}:T{ +New row [a] +T}:T{ +New row +T}:T{ +\(em +T}:T{ +\(em +T}:T{ +\(em +T} +T{ +\fBUPDATE\fR / \fBMERGE \&.\&.\&. THEN UPDATE\fR +T}:T{ +Existing & new rows [a] +T}:T{ +\(em +T}:T{ +Existing row +T}:T{ +New row +T}:T{ +\(em +T} +T{ +\fBDELETE\fR +T}:T{ +Existing row [a] +T}:T{ +\(em +T}:T{ +\(em +T}:T{ +\(em +T}:T{ +Existing row +T} +T{ +\fBON CONFLICT DO UPDATE\fR +T}:T{ +Existing & new rows +T}:T{ +\(em +T}:T{ +Existing row +T}:T{ +New row +T}:T{ +\(em +T} +T{ +---- +.br +[a] +If read access is required to the existing or new row (for example, a +WHERE +or +RETURNING +clause that refers to columns from the relation)\&. +T} +.TE +.sp 1 +.SS "Application of Multiple Policies" +.PP +When multiple policies of different command types apply to the same command (for example, +SELECT +and +UPDATE +policies applied to an +UPDATE +command), then the user must have both types of permissions (for example, permission to select rows from the relation as well as permission to update them)\&. Thus the expressions for one type of policy are combined with the expressions for the other type of policy using the +AND +operator\&. +.PP +When multiple policies of the same command type apply to the same command, then there must be at least one +PERMISSIVE +policy granting access to the relation, and all of the +RESTRICTIVE +policies must pass\&. Thus all the +PERMISSIVE +policy expressions are combined using +OR, all the +RESTRICTIVE +policy expressions are combined using +AND, and the results are combined using +AND\&. If there are no +PERMISSIVE +policies, then access is denied\&. +.PP +Note that, for the purposes of combining multiple policies, +ALL +policies are treated as having the same type as whichever other type of policy is being applied\&. +.PP +For example, in an +UPDATE +command requiring both +SELECT +and +UPDATE +permissions, if there are multiple applicable policies of each type, they will be combined as follows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIexpression\fR from RESTRICTIVE SELECT/ALL policy 1 +AND +\fIexpression\fR from RESTRICTIVE SELECT/ALL policy 2 +AND +\&.\&.\&. +AND +( + \fIexpression\fR from PERMISSIVE SELECT/ALL policy 1 + OR + \fIexpression\fR from PERMISSIVE SELECT/ALL policy 2 + OR + \&.\&.\&. +) +AND +\fIexpression\fR from RESTRICTIVE UPDATE/ALL policy 1 +AND +\fIexpression\fR from RESTRICTIVE UPDATE/ALL policy 2 +AND +\&.\&.\&. +AND +( + \fIexpression\fR from PERMISSIVE UPDATE/ALL policy 1 + OR + \fIexpression\fR from PERMISSIVE UPDATE/ALL policy 2 + OR + \&.\&.\&. +) +.fi +.if n \{\ +.RE +.\} +.SH "NOTES" +.PP +You must be the owner of a table to create or change policies for it\&. +.PP +While policies will be applied for explicit queries against tables in the database, they are not applied when the system is performing internal referential integrity checks or validating constraints\&. This means there are indirect ways to determine that a given value exists\&. An example of this is attempting to insert a duplicate value into a column that is a primary key or has a unique constraint\&. If the insert fails then the user can infer that the value already exists\&. (This example assumes that the user is permitted by policy to insert records which they are not allowed to see\&.) Another example is where a user is allowed to insert into a table which references another, otherwise hidden table\&. Existence can be determined by the user inserting values into the referencing table, where success would indicate that the value exists in the referenced table\&. These issues can be addressed by carefully crafting policies to prevent users from being able to insert, delete, or update records at all which might possibly indicate a value they are not otherwise able to see, or by using generated values (e\&.g\&., surrogate keys) instead of keys with external meanings\&. +.PP +Generally, the system will enforce filter conditions imposed using security policies prior to qualifications that appear in user queries, in order to prevent inadvertent exposure of the protected data to user\-defined functions which might not be trustworthy\&. However, functions and operators marked by the system (or the system administrator) as +LEAKPROOF +may be evaluated before policy expressions, as they are assumed to be trustworthy\&. +.PP +Since policy expressions are added to the user\*(Aqs query directly, they will be run with the rights of the user running the overall query\&. Therefore, users who are using a given policy must be able to access any tables or functions referenced in the expression or they will simply receive a permission denied error when attempting to query the table that has row\-level security enabled\&. This does not change how views work, however\&. As with normal queries and views, permission checks and policies for the tables which are referenced by a view will use the view owner\*(Aqs rights and any policies which apply to the view owner, except if the view is defined using the +security_invoker +option (see +\fBCREATE VIEW\fR)\&. +.PP +No separate policy exists for +\fBMERGE\fR\&. Instead, the policies defined for +\fBSELECT\fR, +\fBINSERT\fR, +\fBUPDATE\fR, and +\fBDELETE\fR +are applied while executing +\fBMERGE\fR, depending on the actions that are performed\&. +.PP +Additional discussion and practical examples can be found in +Section\ \&5.8\&. +.SH "COMPATIBILITY" +.PP +\fBCREATE POLICY\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER POLICY (\fBALTER_POLICY\fR(7)), DROP POLICY (\fBDROP_POLICY\fR(7)), ALTER TABLE (\fBALTER_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_PROCEDURE.7 b/doc/src/sgml/man7/CREATE_PROCEDURE.7 new file mode 100644 index 0000000..7576d6a --- /dev/null +++ b/doc/src/sgml/man7/CREATE_PROCEDURE.7 @@ -0,0 +1,309 @@ +'\" t +.\" Title: CREATE PROCEDURE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE PROCEDURE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_PROCEDURE \- define a new procedure +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] PROCEDURE + \fIname\fR ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ { DEFAULT | = } \fIdefault_expr\fR ] [, \&.\&.\&.] ] ) + { LANGUAGE \fIlang_name\fR + | TRANSFORM { FOR TYPE \fItype_name\fR } [, \&.\&.\&. ] + | [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER + | SET \fIconfiguration_parameter\fR { TO \fIvalue\fR | = \fIvalue\fR | FROM CURRENT } + | AS \*(Aq\fIdefinition\fR\*(Aq + | AS \*(Aq\fIobj_file\fR\*(Aq, \*(Aq\fIlink_symbol\fR\*(Aq + | \fIsql_body\fR + } \&.\&.\&. +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE PROCEDURE\fR +defines a new procedure\&. +\fBCREATE OR REPLACE PROCEDURE\fR +will either create a new procedure, or replace an existing definition\&. To be able to define a procedure, the user must have the +USAGE +privilege on the language\&. +.PP +If a schema name is included, then the procedure is created in the specified schema\&. Otherwise it is created in the current schema\&. The name of the new procedure must not match any existing procedure or function with the same input argument types in the same schema\&. However, procedures and functions of different argument types can share a name (this is called +overloading)\&. +.PP +To replace the current definition of an existing procedure, use +\fBCREATE OR REPLACE PROCEDURE\fR\&. It is not possible to change the name or argument types of a procedure this way (if you tried, you would actually be creating a new, distinct procedure)\&. +.PP +When +\fBCREATE OR REPLACE PROCEDURE\fR +is used to replace an existing procedure, the ownership and permissions of the procedure do not change\&. All other procedure properties are assigned the values specified or implied in the command\&. You must own the procedure to replace it (this includes being a member of the owning role)\&. +.PP +The user that creates the procedure becomes the owner of the procedure\&. +.PP +To be able to create a procedure, you must have +USAGE +privilege on the argument types\&. +.PP +Refer to +Section\ \&38.4 +for further information on writing procedures\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the procedure to create\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type(s) of the procedure\*(Aqs arguments (optionally schema\-qualified), if any\&. The argument types can be base, composite, or domain types, or can reference the type of a table column\&. +.sp +Depending on the implementation language it might also be allowed to specify +\(lqpseudo\-types\(rq +such as +cstring\&. Pseudo\-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types\&. +.sp +The type of a column is referenced by writing +\fItable_name\fR\&.\fIcolumn_name\fR%TYPE\&. Using this feature can sometimes help make a procedure independent of changes to the definition of a table\&. +.RE +.PP +\fIdefault_expr\fR +.RS 4 +An expression to be used as default value if the parameter is not specified\&. The expression has to be coercible to the argument type of the parameter\&. All input parameters following a parameter with a default value must have default values as well\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the language that the procedure is implemented in\&. It can be +sql, +c, +internal, or the name of a user\-defined procedural language, e\&.g\&., +plpgsql\&. The default is +sql +if +\fIsql_body\fR +is specified\&. Enclosing the name in single quotes is deprecated and requires matching case\&. +.RE +.PP +TRANSFORM { FOR TYPE \fItype_name\fR } [, \&.\&.\&. ] } +.RS 4 +Lists which transforms a call to the procedure should apply\&. Transforms convert between SQL types and language\-specific data types; see +CREATE TRANSFORM (\fBCREATE_TRANSFORM\fR(7))\&. Procedural language implementations usually have hardcoded knowledge of the built\-in types, so those don\*(Aqt need to be listed here\&. If a procedural language implementation does not know how to handle a type and no transform is supplied, it will fall back to a default behavior for converting data types, but this depends on the implementation\&. +.RE +.PP +[EXTERNAL] SECURITY INVOKER +.br +[EXTERNAL] SECURITY DEFINER +.RS 4 +SECURITY INVOKER +indicates that the procedure is to be executed with the privileges of the user that calls it\&. That is the default\&. +SECURITY DEFINER +specifies that the procedure is to be executed with the privileges of the user that owns it\&. +.sp +The key word +EXTERNAL +is allowed for SQL conformance, but it is optional since, unlike in SQL, this feature applies to all procedures not only external ones\&. +.sp +A +SECURITY DEFINER +procedure cannot execute transaction control statements (for example, +\fBCOMMIT\fR +and +\fBROLLBACK\fR, depending on the language)\&. +.RE +.PP +\fIconfiguration_parameter\fR +.br +\fIvalue\fR +.RS 4 +The +SET +clause causes the specified configuration parameter to be set to the specified value when the procedure is entered, and then restored to its prior value when the procedure exits\&. +SET FROM CURRENT +saves the value of the parameter that is current when +\fBCREATE PROCEDURE\fR +is executed as the value to be applied when the procedure is entered\&. +.sp +If a +SET +clause is attached to a procedure, then the effects of a +\fBSET LOCAL\fR +command executed inside the procedure for the same variable are restricted to the procedure: the configuration parameter\*(Aqs prior value is still restored at procedure exit\&. However, an ordinary +\fBSET\fR +command (without +LOCAL) overrides the +SET +clause, much as it would do for a previous +\fBSET LOCAL\fR +command: the effects of such a command will persist after procedure exit, unless the current transaction is rolled back\&. +.sp +If a +SET +clause is attached to a procedure, then that procedure cannot execute transaction control statements (for example, +\fBCOMMIT\fR +and +\fBROLLBACK\fR, depending on the language)\&. +.sp +See +\fBSET\fR(7) +and +Chapter\ \&20 +for more information about allowed parameter names and values\&. +.RE +.PP +\fIdefinition\fR +.RS 4 +A string constant defining the procedure; the meaning depends on the language\&. It can be an internal procedure name, the path to an object file, an SQL command, or text in a procedural language\&. +.sp +It is often helpful to use dollar quoting (see +Section\ \&4.1.2.4) to write the procedure definition string, rather than the normal single quote syntax\&. Without dollar quoting, any single quotes or backslashes in the procedure definition must be escaped by doubling them\&. +.RE +.PP +\fIobj_file\fR, \fIlink_symbol\fR +.RS 4 +This form of the +AS +clause is used for dynamically loadable C language procedures when the procedure name in the C language source code is not the same as the name of the SQL procedure\&. The string +\fIobj_file\fR +is the name of the shared library file containing the compiled C procedure, and is interpreted as for the +\fBLOAD\fR +command\&. The string +\fIlink_symbol\fR +is the procedure\*(Aqs link symbol, that is, the name of the procedure in the C language source code\&. If the link symbol is omitted, it is assumed to be the same as the name of the SQL procedure being defined\&. +.sp +When repeated +\fBCREATE PROCEDURE\fR +calls refer to the same object file, the file is only loaded once per session\&. To unload and reload the file (perhaps during development), start a new session\&. +.RE +.PP +\fIsql_body\fR +.RS 4 +The body of a +LANGUAGE SQL +procedure\&. This should be a block +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN ATOMIC + \fIstatement\fR; + \fIstatement\fR; + \&.\&.\&. + \fIstatement\fR; +END +.fi +.if n \{\ +.RE +.\} +.sp +This is similar to writing the text of the procedure body as a string constant (see +\fIdefinition\fR +above), but there are some differences: This form only works for +LANGUAGE SQL, the string constant form works for all languages\&. This form is parsed at procedure definition time, the string constant form is parsed at execution time; therefore this form cannot support polymorphic argument types and other constructs that are not resolvable at procedure definition time\&. This form tracks dependencies between the procedure and objects used in the procedure body, so +DROP \&.\&.\&. CASCADE +will work correctly, whereas the form using string literals may leave dangling procedures\&. Finally, this form is more compatible with the SQL standard and other SQL implementations\&. +.RE +.SH "NOTES" +.PP +See +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) +for more details on function creation that also apply to procedures\&. +.PP +Use +\fBCALL\fR(7) +to execute a procedure\&. +.SH "EXAMPLES" +.PP +.if n \{\ +.RS 4 +.\} +.nf +CREATE PROCEDURE insert_data(a integer, b integer) +LANGUAGE SQL +AS $$ +INSERT INTO tbl VALUES (a); +INSERT INTO tbl VALUES (b); +$$; +.fi +.if n \{\ +.RE +.\} +.sp +or +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PROCEDURE insert_data(a integer, b integer) +LANGUAGE SQL +BEGIN ATOMIC + INSERT INTO tbl VALUES (a); + INSERT INTO tbl VALUES (b); +END; +.fi +.if n \{\ +.RE +.\} +.sp +and call like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CALL insert_data(1, 2); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +A +\fBCREATE PROCEDURE\fR +command is defined in the SQL standard\&. The +PostgreSQL +implementation can be used in a compatible way but has many extensions\&. For details see also +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))\&. +.SH "SEE ALSO" +ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)), DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)), \fBCALL\fR(7), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_PUBLICATION.7 b/doc/src/sgml/man7/CREATE_PUBLICATION.7 new file mode 100644 index 0000000..75a0c83 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_PUBLICATION.7 @@ -0,0 +1,341 @@ +'\" t +.\" Title: CREATE PUBLICATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE PUBLICATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_PUBLICATION \- define a new publication +.SH "SYNOPSIS" +.sp +.nf +CREATE PUBLICATION \fIname\fR + [ FOR ALL TABLES + | FOR \fIpublication_object\fR [, \&.\&.\&. ] ] + [ WITH ( \fIpublication_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] + +where \fIpublication_object\fR is one of: + + TABLE [ ONLY ] \fItable_name\fR [ * ] [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] [ WHERE ( \fIexpression\fR ) ] [, \&.\&.\&. ] + TABLES IN SCHEMA { \fIschema_name\fR | CURRENT_SCHEMA } [, \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE PUBLICATION\fR +adds a new publication into the current database\&. The publication name must be distinct from the name of any existing publication in the current database\&. +.PP +A publication is essentially a group of tables whose data changes are intended to be replicated through logical replication\&. See +Section\ \&31.1 +for details about how publications fit into the logical replication setup\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the new publication\&. +.RE +.PP +FOR TABLE +.RS 4 +Specifies a list of tables to add to the publication\&. If +ONLY +is specified before the table name, only that table is added to the publication\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are added\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. This does not apply to a partitioned table, however\&. The partitions of a partitioned table are always implicitly considered part of the publication, so they are never explicitly added to the publication\&. +.sp +If the optional +WHERE +clause is specified, it defines a +row filter +expression\&. Rows for which the +\fIexpression\fR +evaluates to false or null will not be published\&. Note that parentheses are required around the expression\&. It has no effect on +TRUNCATE +commands\&. +.sp +When a column list is specified, only the named columns are replicated\&. If no column list is specified, all columns of the table are replicated through this publication, including any columns added later\&. It has no effect on +TRUNCATE +commands\&. See +Section\ \&31.4 +for details about column lists\&. +.sp +Only persistent base tables and partitioned tables can be part of a publication\&. Temporary tables, unlogged tables, foreign tables, materialized views, and regular views cannot be part of a publication\&. +.sp +Specifying a column list when the publication also publishes +FOR TABLES IN SCHEMA +is not supported\&. +.sp +When a partitioned table is added to a publication, all of its existing and future partitions are implicitly considered to be part of the publication\&. So, even operations that are performed directly on a partition are also published via publications that its ancestors are part of\&. +.RE +.PP +FOR ALL TABLES +.RS 4 +Marks the publication as one that replicates changes for all tables in the database, including tables created in the future\&. +.RE +.PP +FOR TABLES IN SCHEMA +.RS 4 +Marks the publication as one that replicates changes for all tables in the specified list of schemas, including tables created in the future\&. +.sp +Specifying a schema when the publication also publishes a table with a column list is not supported\&. +.sp +Only persistent base tables and partitioned tables present in the schema will be included as part of the publication\&. Temporary tables, unlogged tables, foreign tables, materialized views, and regular views from the schema will not be part of the publication\&. +.sp +When a partitioned table is published via schema level publication, all of its existing and future partitions are implicitly considered to be part of the publication, regardless of whether they are from the publication schema or not\&. So, even operations that are performed directly on a partition are also published via publications that its ancestors are part of\&. +.RE +.PP +WITH ( \fIpublication_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause specifies optional parameters for a publication\&. The following parameters are supported: +.PP +publish (string) +.RS 4 +This parameter determines which DML operations will be published by the new publication to the subscribers\&. The value is comma\-separated list of operations\&. The allowed operations are +insert, +update, +delete, and +truncate\&. The default is to publish all actions, and so the default value for this option is +\*(Aqinsert, update, delete, truncate\*(Aq\&. +.sp +This parameter only affects DML operations\&. In particular, the initial data synchronization (see +Section\ \&31.7.1) for logical replication does not take this parameter into account when copying existing table data\&. +.RE +.PP +publish_via_partition_root (boolean) +.RS 4 +This parameter determines whether changes in a partitioned table (or on its partitions) contained in the publication will be published using the identity and schema of the partitioned table rather than that of the individual partitions that are actually changed; the latter is the default\&. Enabling this allows the changes to be replicated into a non\-partitioned table or a partitioned table consisting of a different set of partitions\&. +.sp +This parameter also affects how row filters and column lists are chosen for partitions; see below for details\&. +.sp +If this is enabled, +TRUNCATE +operations performed directly on partitions are not replicated\&. +.RE +.RE +.SH "NOTES" +.PP +If +FOR TABLE, +FOR ALL TABLES +or +FOR TABLES IN SCHEMA +are not specified, then the publication starts out with an empty set of tables\&. That is useful if tables or schemas are to be added later\&. +.PP +The creation of a publication does not start replication\&. It only defines a grouping and filtering logic for future subscribers\&. +.PP +To create a publication, the invoking user must have the +CREATE +privilege for the current database\&. (Of course, superusers bypass this check\&.) +.PP +To add a table to a publication, the invoking user must have ownership rights on the table\&. The +\fBFOR ALL TABLES\fR +and +\fBFOR TABLES IN SCHEMA\fR +clauses require the invoking user to be a superuser\&. +.PP +The tables added to a publication that publishes +\fBUPDATE\fR +and/or +\fBDELETE\fR +operations must have +REPLICA IDENTITY +defined\&. Otherwise those operations will be disallowed on those tables\&. +.PP +Any column list must include the +REPLICA IDENTITY +columns in order for +\fBUPDATE\fR +or +\fBDELETE\fR +operations to be published\&. There are no column list restrictions if the publication publishes only +\fBINSERT\fR +operations\&. +.PP +A row filter expression (i\&.e\&., the +WHERE +clause) must contain only columns that are covered by the +REPLICA IDENTITY, in order for +\fBUPDATE\fR +and +\fBDELETE\fR +operations to be published\&. For publication of +\fBINSERT\fR +operations, any column may be used in the +WHERE +expression\&. The row filter allows simple expressions that don\*(Aqt have user\-defined functions, user\-defined operators, user\-defined types, user\-defined collations, non\-immutable built\-in functions, or references to system columns\&. +.PP +The row filter on a table becomes redundant if +FOR TABLES IN SCHEMA +is specified and the table belongs to the referred schema\&. +.PP +For published partitioned tables, the row filter for each partition is taken from the published partitioned table if the publication parameter +publish_via_partition_root +is true, or from the partition itself if it is false (the default)\&. See +Section\ \&31.3 +for details about row filters\&. Similarly, for published partitioned tables, the column list for each partition is taken from the published partitioned table if the publication parameter +publish_via_partition_root +is true, or from the partition itself if it is false\&. +.PP +For an +\fBINSERT \&.\&.\&. ON CONFLICT\fR +command, the publication will publish the operation that results from the command\&. Depending on the outcome, it may be published as either +\fBINSERT\fR +or +\fBUPDATE\fR, or it may not be published at all\&. +.PP +For a +\fBMERGE\fR +command, the publication will publish an +\fBINSERT\fR, +\fBUPDATE\fR, or +\fBDELETE\fR +for each row inserted, updated, or deleted\&. +.PP +\fBATTACH\fRing a table into a partition tree whose root is published using a publication with +publish_via_partition_root +set to +true +does not result in the table\*(Aqs existing contents being replicated\&. +.PP +\fBCOPY \&.\&.\&. FROM\fR +commands are published as +\fBINSERT\fR +operations\&. +.PP +DDL +operations are not published\&. +.PP +The +WHERE +clause expression is executed with the role used for the replication connection\&. +.SH "EXAMPLES" +.PP +Create a publication that publishes all changes in two tables: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION mypublication FOR TABLE users, departments; +.fi +.if n \{\ +.RE +.\} +.PP +Create a publication that publishes all changes from active departments: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION active_departments FOR TABLE departments WHERE (active IS TRUE); +.fi +.if n \{\ +.RE +.\} +.PP +Create a publication that publishes all changes in all tables: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION alltables FOR ALL TABLES; +.fi +.if n \{\ +.RE +.\} +.PP +Create a publication that only publishes +\fBINSERT\fR +operations in one table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION insert_only FOR TABLE mydata + WITH (publish = \*(Aqinsert\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Create a publication that publishes all changes for tables +users, +departments +and all changes for all the tables present in the schema +production: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION production_publication FOR TABLE users, departments, TABLES IN SCHEMA production; +.fi +.if n \{\ +.RE +.\} +.PP +Create a publication that publishes all changes for all the tables present in the schemas +marketing +and +sales: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION sales_publication FOR TABLES IN SCHEMA marketing, sales; +.fi +.if n \{\ +.RE +.\} +.PP +Create a publication that publishes all changes for table +users, but replicates only columns +user_id +and +firstname: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PUBLICATION users_filtered FOR TABLE users (user_id, firstname); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE PUBLICATION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER PUBLICATION (\fBALTER_PUBLICATION\fR(7)), DROP PUBLICATION (\fBDROP_PUBLICATION\fR(7)), CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)), ALTER SUBSCRIPTION (\fBALTER_SUBSCRIPTION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_ROLE.7 b/doc/src/sgml/man7/CREATE_ROLE.7 new file mode 100644 index 0000000..a3ae35e --- /dev/null +++ b/doc/src/sgml/man7/CREATE_ROLE.7 @@ -0,0 +1,427 @@ +'\" t +.\" Title: CREATE ROLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE ROLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_ROLE \- define a new database role +.SH "SYNOPSIS" +.sp +.nf +CREATE ROLE \fIname\fR [ [ WITH ] \fIoption\fR [ \&.\&.\&. ] ] + +where \fIoption\fR can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | REPLICATION | NOREPLICATION + | BYPASSRLS | NOBYPASSRLS + | CONNECTION LIMIT \fIconnlimit\fR + | [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq | PASSWORD NULL + | VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq + | IN ROLE \fIrole_name\fR [, \&.\&.\&.] + | IN GROUP \fIrole_name\fR [, \&.\&.\&.] + | ROLE \fIrole_name\fR [, \&.\&.\&.] + | ADMIN \fIrole_name\fR [, \&.\&.\&.] + | USER \fIrole_name\fR [, \&.\&.\&.] + | SYSID \fIuid\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE ROLE\fR +adds a new role to a +PostgreSQL +database cluster\&. A role is an entity that can own database objects and have database privileges; a role can be considered a +\(lquser\(rq, a +\(lqgroup\(rq, or both depending on how it is used\&. Refer to +Chapter\ \&22 +and +Chapter\ \&21 +for information about managing users and authentication\&. You must have +CREATEROLE +privilege or be a database superuser to use this command\&. +.PP +Note that roles are defined at the database cluster level, and so are valid in all databases in the cluster\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the new role\&. +.RE +.PP +SUPERUSER +.br +NOSUPERUSER +.RS 4 +These clauses determine whether the new role is a +\(lqsuperuser\(rq, who can override all access restrictions within the database\&. Superuser status is dangerous and should be used only when really needed\&. You must yourself be a superuser to create a new superuser\&. If not specified, +NOSUPERUSER +is the default\&. +.RE +.PP +CREATEDB +.br +NOCREATEDB +.RS 4 +These clauses define a role\*(Aqs ability to create databases\&. If +CREATEDB +is specified, the role being defined will be allowed to create new databases\&. Specifying +NOCREATEDB +will deny a role the ability to create databases\&. If not specified, +NOCREATEDB +is the default\&. +.RE +.PP +CREATEROLE +.br +NOCREATEROLE +.RS 4 +These clauses determine whether a role will be permitted to create, alter, drop, comment on, change the security label for, and grant or revoke membership in other roles\&. See +role creation +for more details about what capabilities are conferred by this privilege\&. If not specified, +NOCREATEROLE +is the default\&. +.RE +.PP +INHERIT +.br +NOINHERIT +.RS 4 +These clauses determine whether a role +\(lqinherits\(rq +the privileges of roles it is a member of\&. A role with the +INHERIT +attribute can automatically use whatever database privileges have been granted to all roles it is directly or indirectly a member of\&. Without +INHERIT, membership in another role only grants the ability to +\fBSET ROLE\fR +to that other role; the privileges of the other role are only available after having done so\&. If not specified, +INHERIT +is the default\&. +.RE +.PP +LOGIN +.br +NOLOGIN +.RS 4 +These clauses determine whether a role is allowed to log in; that is, whether the role can be given as the initial session authorization name during client connection\&. A role having the +LOGIN +attribute can be thought of as a user\&. Roles without this attribute are useful for managing database privileges, but are not users in the usual sense of the word\&. If not specified, +NOLOGIN +is the default, except when +\fBCREATE ROLE\fR +is invoked through its alternative spelling +\fBCREATE USER\fR\&. +.RE +.PP +REPLICATION +.br +NOREPLICATION +.RS 4 +These clauses determine whether a role is a replication role\&. A role must have this attribute (or be a superuser) in order to be able to connect to the server in replication mode (physical or logical replication) and in order to be able to create or drop replication slots\&. A role having the +REPLICATION +attribute is a very highly privileged role, and should only be used on roles actually used for replication\&. If not specified, +NOREPLICATION +is the default\&. You must be a superuser to create a new role having the +REPLICATION +attribute\&. +.RE +.PP +BYPASSRLS +.br +NOBYPASSRLS +.RS 4 +These clauses determine whether a role bypasses every row\-level security (RLS) policy\&. +NOBYPASSRLS +is the default\&. You must be a superuser to create a new role having the +BYPASSRLS +attribute\&. +.sp +Note that pg_dump will set +row_security +to +OFF +by default, to ensure all contents of a table are dumped out\&. If the user running pg_dump does not have appropriate permissions, an error will be returned\&. However, superusers and the owner of the table being dumped always bypass RLS\&. +.RE +.PP +CONNECTION LIMIT \fIconnlimit\fR +.RS 4 +If role can log in, this specifies how many concurrent connections the role can make\&. \-1 (the default) means no limit\&. Note that only normal connections are counted towards this limit\&. Neither prepared transactions nor background worker connections are counted towards this limit\&. +.RE +.PP +[ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq +.br +PASSWORD NULL +.RS 4 +Sets the role\*(Aqs password\&. (A password is only of use for roles having the +LOGIN +attribute, but you can nonetheless define one for roles without it\&.) If you do not plan to use password authentication you can omit this option\&. If no password is specified, the password will be set to null and password authentication will always fail for that user\&. A null password can optionally be written explicitly as +PASSWORD NULL\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +Specifying an empty string will also set the password to null, but that was not the case before +PostgreSQL +version 10\&. In earlier versions, an empty string could be used, or not, depending on the authentication method and the exact version, and libpq would refuse to use it in any case\&. To avoid the ambiguity, specifying an empty string should be avoided\&. +.sp .5v +.RE +The password is always stored encrypted in the system catalogs\&. The +ENCRYPTED +keyword has no effect, but is accepted for backwards compatibility\&. The method of encryption is determined by the configuration parameter +password_encryption\&. If the presented password string is already in MD5\-encrypted or SCRAM\-encrypted format, then it is stored as\-is regardless of +\fIpassword_encryption\fR +(since the system cannot decrypt the specified encrypted password string, to encrypt it in a different format)\&. This allows reloading of encrypted passwords during dump/restore\&. +.RE +.PP +VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq +.RS 4 +The +VALID UNTIL +clause sets a date and time after which the role\*(Aqs password is no longer valid\&. If this clause is omitted the password will be valid for all time\&. +.RE +.PP +IN ROLE \fIrole_name\fR +.RS 4 +The +IN ROLE +clause lists one or more existing roles to which the new role will be immediately added as a new member\&. (Note that there is no option to add the new role as an administrator; use a separate +\fBGRANT\fR +command to do that\&.) +.RE +.PP +IN GROUP \fIrole_name\fR +.RS 4 +IN GROUP +is an obsolete spelling of +IN ROLE\&. +.RE +.PP +ROLE \fIrole_name\fR +.RS 4 +The +ROLE +clause lists one or more existing roles which are automatically added as members of the new role\&. (This in effect makes the new role a +\(lqgroup\(rq\&.) +.RE +.PP +ADMIN \fIrole_name\fR +.RS 4 +The +ADMIN +clause is like +ROLE, but the named roles are added to the new role +WITH ADMIN OPTION, giving them the right to grant membership in this role to others\&. +.RE +.PP +USER \fIrole_name\fR +.RS 4 +The +USER +clause is an obsolete spelling of the +ROLE +clause\&. +.RE +.PP +SYSID \fIuid\fR +.RS 4 +The +SYSID +clause is ignored, but is accepted for backwards compatibility\&. +.RE +.SH "NOTES" +.PP +Use +\fBALTER ROLE\fR +to change the attributes of a role, and +\fBDROP ROLE\fR +to remove a role\&. All the attributes specified by +\fBCREATE ROLE\fR +can be modified by later +\fBALTER ROLE\fR +commands\&. +.PP +The preferred way to add and remove members of roles that are being used as groups is to use +\fBGRANT\fR +and +\fBREVOKE\fR\&. +.PP +The +VALID UNTIL +clause defines an expiration time for a password only, not for the role per se\&. In particular, the expiration time is not enforced when logging in using a non\-password\-based authentication method\&. +.PP +The +INHERIT +attribute governs inheritance of grantable privileges (that is, access privileges for database objects and role memberships)\&. It does not apply to the special role attributes set by +\fBCREATE ROLE\fR +and +\fBALTER ROLE\fR\&. For example, being a member of a role with +CREATEDB +privilege does not immediately grant the ability to create databases, even if +INHERIT +is set; it would be necessary to become that role via +\fBSET ROLE\fR +before creating a database\&. +.PP +The +INHERIT +attribute is the default for reasons of backwards compatibility: in prior releases of +PostgreSQL, users always had access to all privileges of groups they were members of\&. However, +NOINHERIT +provides a closer match to the semantics specified in the SQL standard\&. +.PP +Be careful with the +CREATEROLE +privilege\&. There is no concept of inheritance for the privileges of a +CREATEROLE\-role\&. That means that even if a role does not have a certain privilege but is allowed to create other roles, it can easily create another role with different privileges than its own (except for creating roles with superuser privileges)\&. For example, if the role +\(lquser\(rq +has the +CREATEROLE +privilege but not the +CREATEDB +privilege, nonetheless it can create a new role with the +CREATEDB +privilege\&. Therefore, regard roles that have the +CREATEROLE +privilege as almost\-superuser\-roles\&. +.PP +PostgreSQL +includes a program +\fBcreateuser\fR(1) +that has the same functionality as +\fBCREATE ROLE\fR +(in fact, it calls this command) but can be run from the command shell\&. +.PP +The +CONNECTION LIMIT +option is only enforced approximately; if two new sessions start at about the same time when just one connection +\(lqslot\(rq +remains for the role, it is possible that both will fail\&. Also, the limit is never enforced for superusers\&. +.PP +Caution must be exercised when specifying an unencrypted password with this command\&. The password will be transmitted to the server in cleartext, and it might also be logged in the client\*(Aqs command history or the server log\&. The command +\fBcreateuser\fR(1), however, transmits the password encrypted\&. Also, +\fBpsql\fR(1) +contains a command +\fB\epassword\fR +that can be used to safely change the password later\&. +.SH "EXAMPLES" +.PP +Create a role that can log in, but don\*(Aqt give it a password: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE ROLE jonathan LOGIN; +.fi +.if n \{\ +.RE +.\} +.PP +Create a role with a password: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE USER davide WITH PASSWORD \*(Aqjw8s0F4\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +(\fBCREATE USER\fR +is the same as +\fBCREATE ROLE\fR +except that it implies +LOGIN\&.) +.PP +Create a role with a password that is valid until the end of 2004\&. After one second has ticked in 2005, the password is no longer valid\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE ROLE miriam WITH LOGIN PASSWORD \*(Aqjw8s0F4\*(Aq VALID UNTIL \*(Aq2005\-01\-01\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Create a role that can create databases and manage roles: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE ROLE admin WITH CREATEDB CREATEROLE; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBCREATE ROLE\fR +statement is in the SQL standard, but the standard only requires the syntax +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE ROLE \fIname\fR [ WITH ADMIN \fIrole_name\fR ] +.fi +.if n \{\ +.RE +.\} +.sp +Multiple initial administrators, and all the other options of +\fBCREATE ROLE\fR, are +PostgreSQL +extensions\&. +.PP +The SQL standard defines the concepts of users and roles, but it regards them as distinct concepts and leaves all commands defining users to be specified by each database implementation\&. In +PostgreSQL +we have chosen to unify users and roles into a single kind of entity\&. Roles therefore have many more optional attributes than they do in the standard\&. +.PP +The behavior specified by the SQL standard is most closely approximated by giving users the +NOINHERIT +attribute, while roles are given the +INHERIT +attribute\&. +.SH "SEE ALSO" +SET ROLE (\fBSET_ROLE\fR(7)), ALTER ROLE (\fBALTER_ROLE\fR(7)), DROP ROLE (\fBDROP_ROLE\fR(7)), \fBGRANT\fR(7), \fBREVOKE\fR(7), \fBcreateuser\fR(1) diff --git a/doc/src/sgml/man7/CREATE_RULE.7 b/doc/src/sgml/man7/CREATE_RULE.7 new file mode 100644 index 0000000..a7b6d42 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_RULE.7 @@ -0,0 +1,295 @@ +'\" t +.\" Title: CREATE RULE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE RULE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_RULE \- define a new rewrite rule +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] RULE \fIname\fR AS ON \fIevent\fR + TO \fItable_name\fR [ WHERE \fIcondition\fR ] + DO [ ALSO | INSTEAD ] { NOTHING | \fIcommand\fR | ( \fIcommand\fR ; \fIcommand\fR \&.\&.\&. ) } + +where \fIevent\fR can be one of: + + SELECT | INSERT | UPDATE | DELETE +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE RULE\fR +defines a new rule applying to a specified table or view\&. +\fBCREATE OR REPLACE RULE\fR +will either create a new rule, or replace an existing rule of the same name for the same table\&. +.PP +The +PostgreSQL +rule system allows one to define an alternative action to be performed on insertions, updates, or deletions in database tables\&. Roughly speaking, a rule causes additional commands to be executed when a given command on a given table is executed\&. Alternatively, an +INSTEAD +rule can replace a given command by another, or cause a command not to be executed at all\&. Rules are used to implement SQL views as well\&. It is important to realize that a rule is really a command transformation mechanism, or command macro\&. The transformation happens before the execution of the command starts\&. If you actually want an operation that fires independently for each physical row, you probably want to use a trigger, not a rule\&. More information about the rules system is in +Chapter\ \&41\&. +.PP +Presently, +ON SELECT +rules can only be attached to views\&. (Attaching one to a table converts the table into a view\&.) Such a rule must be named +"_RETURN", must be an unconditional +INSTEAD +rule, and must have an action that consists of a single +\fBSELECT\fR +command\&. This command defines the visible contents of the view\&. (The view itself is basically a dummy table with no storage\&.) It\*(Aqs best to regard such a rule as an implementation detail\&. While a view can be redefined via +CREATE OR REPLACE RULE "_RETURN" AS \&.\&.\&., it\*(Aqs better style to use +CREATE OR REPLACE VIEW\&. +.PP +You can create the illusion of an updatable view by defining +ON INSERT, +ON UPDATE, and +ON DELETE +rules (or any subset of those that\*(Aqs sufficient for your purposes) to replace update actions on the view with appropriate updates on other tables\&. If you want to support +\fBINSERT RETURNING\fR +and so on, then be sure to put a suitable +RETURNING +clause into each of these rules\&. +.PP +There is a catch if you try to use conditional rules for complex view updates: there +\fImust\fR +be an unconditional +INSTEAD +rule for each action you wish to allow on the view\&. If the rule is conditional, or is not +INSTEAD, then the system will still reject attempts to perform the update action, because it thinks it might end up trying to perform the action on the dummy table of the view in some cases\&. If you want to handle all the useful cases in conditional rules, add an unconditional +DO INSTEAD NOTHING +rule to ensure that the system understands it will never be called on to update the dummy table\&. Then make the conditional rules non\-INSTEAD; in the cases where they are applied, they add to the default +INSTEAD NOTHING +action\&. (This method does not currently work to support +RETURNING +queries, however\&.) +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +A view that is simple enough to be automatically updatable (see +CREATE VIEW (\fBCREATE_VIEW\fR(7))) does not require a user\-created rule in order to be updatable\&. While you can create an explicit rule anyway, the automatic update transformation will generally outperform an explicit rule\&. +.PP +Another alternative worth considering is to use +INSTEAD OF +triggers (see +CREATE TRIGGER (\fBCREATE_TRIGGER\fR(7))) in place of rules\&. +.sp .5v +.RE +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of a rule to create\&. This must be distinct from the name of any other rule for the same table\&. Multiple rules on the same table and same event type are applied in alphabetical name order\&. +.RE +.PP +\fIevent\fR +.RS 4 +The event is one of +SELECT, +INSERT, +UPDATE, or +DELETE\&. Note that an +\fBINSERT\fR +containing an +ON CONFLICT +clause cannot be used on tables that have either +INSERT +or +UPDATE +rules\&. Consider using an updatable view instead\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table or view the rule applies to\&. +.RE +.PP +\fIcondition\fR +.RS 4 +Any +SQL +conditional expression (returning +boolean)\&. The condition expression cannot refer to any tables except +NEW +and +OLD, and cannot contain aggregate functions\&. +.RE +.PP +\fBINSTEAD\fR +.RS 4 +INSTEAD +indicates that the commands should be executed +\fIinstead of\fR +the original command\&. +.RE +.PP +\fBALSO\fR +.RS 4 +ALSO +indicates that the commands should be executed +\fIin addition to\fR +the original command\&. +.sp +If neither +ALSO +nor +INSTEAD +is specified, +ALSO +is the default\&. +.RE +.PP +\fIcommand\fR +.RS 4 +The command or commands that make up the rule action\&. Valid commands are +\fBSELECT\fR, +\fBINSERT\fR, +\fBUPDATE\fR, +\fBDELETE\fR, or +\fBNOTIFY\fR\&. +.RE +.PP +Within +\fIcondition\fR +and +\fIcommand\fR, the special table names +NEW +and +OLD +can be used to refer to values in the referenced table\&. +NEW +is valid in +ON INSERT +and +ON UPDATE +rules to refer to the new row being inserted or updated\&. +OLD +is valid in +ON UPDATE +and +ON DELETE +rules to refer to the existing row being updated or deleted\&. +.SH "NOTES" +.PP +You must be the owner of a table to create or change rules for it\&. +.PP +In a rule for +INSERT, +UPDATE, or +DELETE +on a view, you can add a +RETURNING +clause that emits the view\*(Aqs columns\&. This clause will be used to compute the outputs if the rule is triggered by an +\fBINSERT RETURNING\fR, +\fBUPDATE RETURNING\fR, or +\fBDELETE RETURNING\fR +command respectively\&. When the rule is triggered by a command without +RETURNING, the rule\*(Aqs +RETURNING +clause will be ignored\&. The current implementation allows only unconditional +INSTEAD +rules to contain +RETURNING; furthermore there can be at most one +RETURNING +clause among all the rules for the same event\&. (This ensures that there is only one candidate +RETURNING +clause to be used to compute the results\&.) +RETURNING +queries on the view will be rejected if there is no +RETURNING +clause in any available rule\&. +.PP +It is very important to take care to avoid circular rules\&. For example, though each of the following two rule definitions are accepted by +PostgreSQL, the +\fBSELECT\fR +command would cause +PostgreSQL +to report an error because of recursive expansion of a rule: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE RULE "_RETURN" AS + ON SELECT TO t1 + DO INSTEAD + SELECT * FROM t2; + +CREATE RULE "_RETURN" AS + ON SELECT TO t2 + DO INSTEAD + SELECT * FROM t1; + +SELECT * FROM t1; +.fi +.if n \{\ +.RE +.\} +.PP +Presently, if a rule action contains a +\fBNOTIFY\fR +command, the +\fBNOTIFY\fR +command will be executed unconditionally, that is, the +\fBNOTIFY\fR +will be issued even if there are not any rows that the rule should apply to\&. For example, in: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE RULE notify_me AS ON UPDATE TO mytable DO ALSO NOTIFY mytable; + +UPDATE mytable SET name = \*(Aqfoo\*(Aq WHERE id = 42; +.fi +.if n \{\ +.RE +.\} +.sp +one +\fBNOTIFY\fR +event will be sent during the +\fBUPDATE\fR, whether or not there are any rows that match the condition +id = 42\&. This is an implementation restriction that might be fixed in future releases\&. +.SH "COMPATIBILITY" +.PP +\fBCREATE RULE\fR +is a +PostgreSQL +language extension, as is the entire query rewrite system\&. +.SH "SEE ALSO" +ALTER RULE (\fBALTER_RULE\fR(7)), DROP RULE (\fBDROP_RULE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_SCHEMA.7 b/doc/src/sgml/man7/CREATE_SCHEMA.7 new file mode 100644 index 0000000..545f33e --- /dev/null +++ b/doc/src/sgml/man7/CREATE_SCHEMA.7 @@ -0,0 +1,207 @@ +'\" t +.\" Title: CREATE SCHEMA +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE SCHEMA" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_SCHEMA \- define a new schema +.SH "SYNOPSIS" +.sp +.nf +CREATE SCHEMA \fIschema_name\fR [ AUTHORIZATION \fIrole_specification\fR ] [ \fIschema_element\fR [ \&.\&.\&. ] ] +CREATE SCHEMA AUTHORIZATION \fIrole_specification\fR [ \fIschema_element\fR [ \&.\&.\&. ] ] +CREATE SCHEMA IF NOT EXISTS \fIschema_name\fR [ AUTHORIZATION \fIrole_specification\fR ] +CREATE SCHEMA IF NOT EXISTS AUTHORIZATION \fIrole_specification\fR + +where \fIrole_specification\fR can be: + + \fIuser_name\fR + | CURRENT_ROLE + | CURRENT_USER + | SESSION_USER +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE SCHEMA\fR +enters a new schema into the current database\&. The schema name must be distinct from the name of any existing schema in the current database\&. +.PP +A schema is essentially a namespace: it contains named objects (tables, data types, functions, and operators) whose names can duplicate those of other objects existing in other schemas\&. Named objects are accessed either by +\(lqqualifying\(rq +their names with the schema name as a prefix, or by setting a search path that includes the desired schema(s)\&. A +CREATE +command specifying an unqualified object name creates the object in the current schema (the one at the front of the search path, which can be determined with the function +\fBcurrent_schema\fR)\&. +.PP +Optionally, +\fBCREATE SCHEMA\fR +can include subcommands to create objects within the new schema\&. The subcommands are treated essentially the same as separate commands issued after creating the schema, except that if the +AUTHORIZATION +clause is used, all the created objects will be owned by that user\&. +.SH "PARAMETERS" +.PP +\fIschema_name\fR +.RS 4 +The name of a schema to be created\&. If this is omitted, the +\fIuser_name\fR +is used as the schema name\&. The name cannot begin with +pg_, as such names are reserved for system schemas\&. +.RE +.PP +\fIuser_name\fR +.RS 4 +The role name of the user who will own the new schema\&. If omitted, defaults to the user executing the command\&. To create a schema owned by another role, you must be a direct or indirect member of that role, or be a superuser\&. +.RE +.PP +\fIschema_element\fR +.RS 4 +An SQL statement defining an object to be created within the schema\&. Currently, only +\fBCREATE TABLE\fR, +\fBCREATE VIEW\fR, +\fBCREATE INDEX\fR, +\fBCREATE SEQUENCE\fR, +\fBCREATE TRIGGER\fR +and +\fBGRANT\fR +are accepted as clauses within +\fBCREATE SCHEMA\fR\&. Other kinds of objects may be created in separate commands after the schema is created\&. +.RE +.PP +IF NOT EXISTS +.RS 4 +Do nothing (except issuing a notice) if a schema with the same name already exists\&. +\fIschema_element\fR +subcommands cannot be included when this option is used\&. +.RE +.SH "NOTES" +.PP +To create a schema, the invoking user must have the +CREATE +privilege for the current database\&. (Of course, superusers bypass this check\&.) +.SH "EXAMPLES" +.PP +Create a schema: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SCHEMA myschema; +.fi +.if n \{\ +.RE +.\} +.PP +Create a schema for user +joe; the schema will also be named +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SCHEMA AUTHORIZATION joe; +.fi +.if n \{\ +.RE +.\} +.PP +Create a schema named +test +that will be owned by user +joe, unless there already is a schema named +test\&. (It does not matter whether +joe +owns the pre\-existing schema\&.) +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SCHEMA IF NOT EXISTS test AUTHORIZATION joe; +.fi +.if n \{\ +.RE +.\} +.PP +Create a schema and create a table and view within it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SCHEMA hollywood + CREATE TABLE films (title text, release date, awards text[]) + CREATE VIEW winners AS + SELECT title, release FROM films WHERE awards IS NOT NULL; +.fi +.if n \{\ +.RE +.\} +.sp +Notice that the individual subcommands do not end with semicolons\&. +.PP +The following is an equivalent way of accomplishing the same result: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SCHEMA hollywood; +CREATE TABLE hollywood\&.films (title text, release date, awards text[]); +CREATE VIEW hollywood\&.winners AS + SELECT title, release FROM hollywood\&.films WHERE awards IS NOT NULL; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The SQL standard allows a +DEFAULT CHARACTER SET +clause in +\fBCREATE SCHEMA\fR, as well as more subcommand types than are presently accepted by +PostgreSQL\&. +.PP +The SQL standard specifies that the subcommands in +\fBCREATE SCHEMA\fR +can appear in any order\&. The present +PostgreSQL +implementation does not handle all cases of forward references in subcommands; it might sometimes be necessary to reorder the subcommands in order to avoid forward references\&. +.PP +According to the SQL standard, the owner of a schema always owns all objects within it\&. +PostgreSQL +allows schemas to contain objects owned by users other than the schema owner\&. This can happen only if the schema owner grants the +CREATE +privilege on their schema to someone else, or a superuser chooses to create objects in it\&. +.PP +The +IF NOT EXISTS +option is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER SCHEMA (\fBALTER_SCHEMA\fR(7)), DROP SCHEMA (\fBDROP_SCHEMA\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_SEQUENCE.7 b/doc/src/sgml/man7/CREATE_SEQUENCE.7 new file mode 100644 index 0000000..2f1ee35 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_SEQUENCE.7 @@ -0,0 +1,357 @@ +'\" t +.\" Title: CREATE SEQUENCE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE SEQUENCE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_SEQUENCE \- define a new sequence generator +.SH "SYNOPSIS" +.sp +.nf +CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] \fIname\fR + [ AS \fIdata_type\fR ] + [ INCREMENT [ BY ] \fIincrement\fR ] + [ MINVALUE \fIminvalue\fR | NO MINVALUE ] [ MAXVALUE \fImaxvalue\fR | NO MAXVALUE ] + [ START [ WITH ] \fIstart\fR ] [ CACHE \fIcache\fR ] [ [ NO ] CYCLE ] + [ OWNED BY { \fItable_name\fR\&.\fIcolumn_name\fR | NONE } ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE SEQUENCE\fR +creates a new sequence number generator\&. This involves creating and initializing a new special single\-row table with the name +\fIname\fR\&. The generator will be owned by the user issuing the command\&. +.PP +If a schema name is given then the sequence is created in the specified schema\&. Otherwise it is created in the current schema\&. Temporary sequences exist in a special schema, so a schema name cannot be given when creating a temporary sequence\&. The sequence name must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema\&. +.PP +After a sequence is created, you use the functions +\fBnextval\fR, +\fBcurrval\fR, and +\fBsetval\fR +to operate on the sequence\&. These functions are documented in +Section\ \&9.17\&. +.PP +Although you cannot update a sequence directly, you can use a query like: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM \fIname\fR; +.fi +.if n \{\ +.RE +.\} +.sp +to examine the parameters and current state of a sequence\&. In particular, the +last_value +field of the sequence shows the last value allocated by any session\&. (Of course, this value might be obsolete by the time it\*(Aqs printed, if other sessions are actively doing +\fBnextval\fR +calls\&.) +.SH "PARAMETERS" +.PP +TEMPORARY or TEMP +.RS 4 +If specified, the sequence object is created only for this session, and is automatically dropped on session exit\&. Existing permanent sequences with the same name are not visible (in this session) while the temporary sequence exists, unless they are referenced with schema\-qualified names\&. +.RE +.PP +UNLOGGED +.RS 4 +If specified, the sequence is created as an unlogged sequence\&. Changes to unlogged sequences are not written to the write\-ahead log\&. They are not crash\-safe: an unlogged sequence is automatically reset to its initial state after a crash or unclean shutdown\&. Unlogged sequences are also not replicated to standby servers\&. +.sp +Unlike unlogged tables, unlogged sequences do not offer a significant performance advantage\&. This option is mainly intended for sequences associated with unlogged tables via identity columns or serial columns\&. In those cases, it usually wouldn\*(Aqt make sense to have the sequence WAL\-logged and replicated but not its associated table\&. +.RE +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a relation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing relation is anything like the sequence that would have been created \(em it might not even be a sequence\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the sequence to be created\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The optional clause +AS \fIdata_type\fR +specifies the data type of the sequence\&. Valid types are +smallint, +integer, and +bigint\&. +bigint +is the default\&. The data type determines the default minimum and maximum values of the sequence\&. +.RE +.PP +\fIincrement\fR +.RS 4 +The optional clause +INCREMENT BY \fIincrement\fR +specifies which value is added to the current sequence value to create a new value\&. A positive value will make an ascending sequence, a negative one a descending sequence\&. The default value is 1\&. +.RE +.PP +\fIminvalue\fR +.br +NO MINVALUE +.RS 4 +The optional clause +MINVALUE \fIminvalue\fR +determines the minimum value a sequence can generate\&. If this clause is not supplied or +\fBNO MINVALUE\fR +is specified, then defaults will be used\&. The default for an ascending sequence is 1\&. The default for a descending sequence is the minimum value of the data type\&. +.RE +.PP +\fImaxvalue\fR +.br +NO MAXVALUE +.RS 4 +The optional clause +MAXVALUE \fImaxvalue\fR +determines the maximum value for the sequence\&. If this clause is not supplied or +\fBNO MAXVALUE\fR +is specified, then default values will be used\&. The default for an ascending sequence is the maximum value of the data type\&. The default for a descending sequence is \-1\&. +.RE +.PP +\fIstart\fR +.RS 4 +The optional clause +START WITH \fIstart\fR +allows the sequence to begin anywhere\&. The default starting value is +\fIminvalue\fR +for ascending sequences and +\fImaxvalue\fR +for descending ones\&. +.RE +.PP +\fIcache\fR +.RS 4 +The optional clause +CACHE \fIcache\fR +specifies how many sequence numbers are to be preallocated and stored in memory for faster access\&. The minimum value is 1 (only one value can be generated at a time, i\&.e\&., no cache), and this is also the default\&. +.RE +.PP +CYCLE +.br +NO CYCLE +.RS 4 +The +CYCLE +option allows the sequence to wrap around when the +\fImaxvalue\fR +or +\fIminvalue\fR +has been reached by an ascending or descending sequence respectively\&. If the limit is reached, the next number generated will be the +\fIminvalue\fR +or +\fImaxvalue\fR, respectively\&. +.sp +If +NO CYCLE +is specified, any calls to +\fBnextval\fR +after the sequence has reached its maximum value will return an error\&. If neither +CYCLE +or +NO CYCLE +are specified, +NO CYCLE +is the default\&. +.RE +.PP +OWNED BY \fItable_name\fR\&.\fIcolumn_name\fR +.br +OWNED BY NONE +.RS 4 +The +OWNED BY +option causes the sequence to be associated with a specific table column, such that if that column (or its whole table) is dropped, the sequence will be automatically dropped as well\&. The specified table must have the same owner and be in the same schema as the sequence\&. +OWNED BY NONE, the default, specifies that there is no such association\&. +.RE +.SH "NOTES" +.PP +Use +\fBDROP SEQUENCE\fR +to remove a sequence\&. +.PP +Sequences are based on +bigint +arithmetic, so the range cannot exceed the range of an eight\-byte integer (\-9223372036854775808 to 9223372036854775807)\&. +.PP +Because +\fBnextval\fR +and +\fBsetval\fR +calls are never rolled back, sequence objects cannot be used if +\(lqgapless\(rq +assignment of sequence numbers is needed\&. It is possible to build gapless assignment by using exclusive locking of a table containing a counter; but this solution is much more expensive than sequence objects, especially if many transactions need sequence numbers concurrently\&. +.PP +Unexpected results might be obtained if a +\fIcache\fR +setting greater than one is used for a sequence object that will be used concurrently by multiple sessions\&. Each session will allocate and cache successive sequence values during one access to the sequence object and increase the sequence object\*(Aqs +last_value +accordingly\&. Then, the next +\fIcache\fR\-1 uses of +\fBnextval\fR +within that session simply return the preallocated values without touching the sequence object\&. So, any numbers allocated but not used within a session will be lost when that session ends, resulting in +\(lqholes\(rq +in the sequence\&. +.PP +Furthermore, although multiple sessions are guaranteed to allocate distinct sequence values, the values might be generated out of sequence when all the sessions are considered\&. For example, with a +\fIcache\fR +setting of 10, session A might reserve values 1\&.\&.10 and return +\fBnextval\fR=1, then session B might reserve values 11\&.\&.20 and return +\fBnextval\fR=11 before session A has generated +\fBnextval\fR=2\&. Thus, with a +\fIcache\fR +setting of one it is safe to assume that +\fBnextval\fR +values are generated sequentially; with a +\fIcache\fR +setting greater than one you should only assume that the +\fBnextval\fR +values are all distinct, not that they are generated purely sequentially\&. Also, +last_value +will reflect the latest value reserved by any session, whether or not it has yet been returned by +\fBnextval\fR\&. +.PP +Another consideration is that a +\fBsetval\fR +executed on such a sequence will not be noticed by other sessions until they have used up any preallocated values they have cached\&. +.SH "EXAMPLES" +.PP +Create an ascending sequence called +serial, starting at 101: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SEQUENCE serial START 101; +.fi +.if n \{\ +.RE +.\} +.PP +Select the next number from this sequence: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT nextval(\*(Aqserial\*(Aq); + + nextval +\-\-\-\-\-\-\-\-\- + 101 +.fi +.if n \{\ +.RE +.\} +.PP +Select the next number from this sequence: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT nextval(\*(Aqserial\*(Aq); + + nextval +\-\-\-\-\-\-\-\-\- + 102 +.fi +.if n \{\ +.RE +.\} +.PP +Use this sequence in an +\fBINSERT\fR +command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO distributors VALUES (nextval(\*(Aqserial\*(Aq), \*(Aqnothing\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Update the sequence value after a +\fBCOPY FROM\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; +COPY distributors FROM \*(Aqinput_file\*(Aq; +SELECT setval(\*(Aqserial\*(Aq, max(id)) FROM distributors; +END; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE SEQUENCE\fR +conforms to the +SQL +standard, with the following exceptions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Obtaining the next value is done using the +\fBnextval()\fR +function instead of the standard\*(Aqs +\fBNEXT VALUE FOR\fR +expression\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +OWNED BY +clause is a +PostgreSQL +extension\&. +.RE +.SH "SEE ALSO" +ALTER SEQUENCE (\fBALTER_SEQUENCE\fR(7)), DROP SEQUENCE (\fBDROP_SEQUENCE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_SERVER.7 b/doc/src/sgml/man7/CREATE_SERVER.7 new file mode 100644 index 0000000..a28fbcb --- /dev/null +++ b/doc/src/sgml/man7/CREATE_SERVER.7 @@ -0,0 +1,118 @@ +'\" t +.\" Title: CREATE SERVER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE SERVER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_SERVER \- define a new foreign server +.SH "SYNOPSIS" +.sp +.nf +CREATE SERVER [ IF NOT EXISTS ] \fIserver_name\fR [ TYPE \*(Aq\fIserver_type\fR\*(Aq ] [ VERSION \*(Aq\fIserver_version\fR\*(Aq ] + FOREIGN DATA WRAPPER \fIfdw_name\fR + [ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE SERVER\fR +defines a new foreign server\&. The user who defines the server becomes its owner\&. +.PP +A foreign server typically encapsulates connection information that a foreign\-data wrapper uses to access an external data resource\&. Additional user\-specific connection information may be specified by means of user mappings\&. +.PP +The server name must be unique within the database\&. +.PP +Creating a server requires +USAGE +privilege on the foreign\-data wrapper being used\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a server with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing server is anything like the one that would have been created\&. +.RE +.PP +\fIserver_name\fR +.RS 4 +The name of the foreign server to be created\&. +.RE +.PP +\fIserver_type\fR +.RS 4 +Optional server type, potentially useful to foreign\-data wrappers\&. +.RE +.PP +\fIserver_version\fR +.RS 4 +Optional server version, potentially useful to foreign\-data wrappers\&. +.RE +.PP +\fIfdw_name\fR +.RS 4 +The name of the foreign\-data wrapper that manages the server\&. +.RE +.PP +OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) +.RS 4 +This clause specifies the options for the server\&. The options typically define the connection details of the server, but the actual names and values are dependent on the server\*(Aqs foreign\-data wrapper\&. +.RE +.SH "NOTES" +.PP +When using the +dblink +module, a foreign server\*(Aqs name can be used as an argument of the +\fBdblink_connect\fR(3) +function to indicate the connection parameters\&. It is necessary to have the +USAGE +privilege on the foreign server to be able to use it in this way\&. +.PP +If the foreign server supports sort pushdown, it is necessary for it to have the same sort ordering as the local server\&. +.SH "EXAMPLES" +.PP +Create a server +myserver +that uses the foreign\-data wrapper +postgres_fdw: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SERVER myserver FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host \*(Aqfoo\*(Aq, dbname \*(Aqfoodb\*(Aq, port \*(Aq5432\*(Aq); +.fi +.if n \{\ +.RE +.\} +.sp +See +postgres_fdw +for more details\&. +.SH "COMPATIBILITY" +.PP +\fBCREATE SERVER\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. +.SH "SEE ALSO" +ALTER SERVER (\fBALTER_SERVER\fR(7)), DROP SERVER (\fBDROP_SERVER\fR(7)), CREATE FOREIGN DATA WRAPPER (\fBCREATE_FOREIGN_DATA_WRAPPER\fR(7)), CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)), CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_STATISTICS.7 b/doc/src/sgml/man7/CREATE_STATISTICS.7 new file mode 100644 index 0000000..e54c236 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_STATISTICS.7 @@ -0,0 +1,236 @@ +'\" t +.\" Title: CREATE STATISTICS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE STATISTICS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_STATISTICS \- define extended statistics +.SH "SYNOPSIS" +.sp +.nf +CREATE STATISTICS [ IF NOT EXISTS ] \fIstatistics_name\fR + ON ( \fIexpression\fR ) + FROM \fItable_name\fR + +CREATE STATISTICS [ IF NOT EXISTS ] \fIstatistics_name\fR + [ ( \fIstatistics_kind\fR [, \&.\&.\&. ] ) ] + ON { \fIcolumn_name\fR | ( \fIexpression\fR ) }, { \fIcolumn_name\fR | ( \fIexpression\fR ) } [, \&.\&.\&.] + FROM \fItable_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE STATISTICS\fR +will create a new extended statistics object tracking data about the specified table, foreign table or materialized view\&. The statistics object will be created in the current database and will be owned by the user issuing the command\&. +.PP +The +\fBCREATE STATISTICS\fR +command has two basic forms\&. The first form allows univariate statistics for a single expression to be collected, providing benefits similar to an expression index without the overhead of index maintenance\&. This form does not allow the statistics kind to be specified, since the various statistics kinds refer only to multivariate statistics\&. The second form of the command allows multivariate statistics on multiple columns and/or expressions to be collected, optionally specifying which statistics kinds to include\&. This form will also automatically cause univariate statistics to be collected on any expressions included in the list\&. +.PP +If a schema name is given (for example, +CREATE STATISTICS myschema\&.mystat \&.\&.\&.) then the statistics object is created in the specified schema\&. Otherwise it is created in the current schema\&. The name of the statistics object must be distinct from the name of any other statistics object in the same schema\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a statistics object with the same name already exists\&. A notice is issued in this case\&. Note that only the name of the statistics object is considered here, not the details of its definition\&. +.RE +.PP +\fIstatistics_name\fR +.RS 4 +The name (optionally schema\-qualified) of the statistics object to be created\&. +.RE +.PP +\fIstatistics_kind\fR +.RS 4 +A multivariate statistics kind to be computed in this statistics object\&. Currently supported kinds are +ndistinct, which enables n\-distinct statistics, +dependencies, which enables functional dependency statistics, and +mcv +which enables most\-common values lists\&. If this clause is omitted, all supported statistics kinds are included in the statistics object\&. Univariate expression statistics are built automatically if the statistics definition includes any complex expressions rather than just simple column references\&. For more information, see +Section\ \&14.2.2 +and +Section\ \&75.2\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a table column to be covered by the computed statistics\&. This is only allowed when building multivariate statistics\&. At least two column names or expressions must be specified, and their order is not significant\&. +.RE +.PP +\fIexpression\fR +.RS 4 +An expression to be covered by the computed statistics\&. This may be used to build univariate statistics on a single expression, or as part of a list of multiple column names and/or expressions to build multivariate statistics\&. In the latter case, separate univariate statistics are built automatically for each expression in the list\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table containing the column(s) the statistics are computed on; see +\fBANALYZE\fR(7) +for an explanation of the handling of inheritance and partitions\&. +.RE +.SH "NOTES" +.PP +You must be the owner of a table to create a statistics object reading it\&. Once created, however, the ownership of the statistics object is independent of the underlying table(s)\&. +.PP +Expression statistics are per\-expression and are similar to creating an index on the expression, except that they avoid the overhead of index maintenance\&. Expression statistics are built automatically for each expression in the statistics object definition\&. +.PP +Extended statistics are not currently used by the planner for selectivity estimations made for table joins\&. This limitation will likely be removed in a future version of +PostgreSQL\&. +.SH "EXAMPLES" +.PP +Create table +t1 +with two functionally dependent columns, i\&.e\&., knowledge of a value in the first column is sufficient for determining the value in the other column\&. Then functional dependency statistics are built on those columns: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE t1 ( + a int, + b int +); + +INSERT INTO t1 SELECT i/100, i/500 + FROM generate_series(1,1000000) s(i); + +ANALYZE t1; + +\-\- the number of matching rows will be drastically underestimated: +EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); + +CREATE STATISTICS s1 (dependencies) ON a, b FROM t1; + +ANALYZE t1; + +\-\- now the row count estimate is more accurate: +EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); +.fi +.if n \{\ +.RE +.\} +.sp +Without functional\-dependency statistics, the planner would assume that the two +WHERE +conditions are independent, and would multiply their selectivities together to arrive at a much\-too\-small row count estimate\&. With such statistics, the planner recognizes that the +WHERE +conditions are redundant and does not underestimate the row count\&. +.PP +Create table +t2 +with two perfectly correlated columns (containing identical data), and an MCV list on those columns: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE t2 ( + a int, + b int +); + +INSERT INTO t2 SELECT mod(i,100), mod(i,100) + FROM generate_series(1,1000000) s(i); + +CREATE STATISTICS s2 (mcv) ON a, b FROM t2; + +ANALYZE t2; + +\-\- valid combination (found in MCV) +EXPLAIN ANALYZE SELECT * FROM t2 WHERE (a = 1) AND (b = 1); + +\-\- invalid combination (not found in MCV) +EXPLAIN ANALYZE SELECT * FROM t2 WHERE (a = 1) AND (b = 2); +.fi +.if n \{\ +.RE +.\} +.sp +The MCV list gives the planner more detailed information about the specific values that commonly appear in the table, as well as an upper bound on the selectivities of combinations of values that do not appear in the table, allowing it to generate better estimates in both cases\&. +.PP +Create table +t3 +with a single timestamp column, and run queries using expressions on that column\&. Without extended statistics, the planner has no information about the data distribution for the expressions, and uses default estimates\&. The planner also does not realize that the value of the date truncated to the month is fully determined by the value of the date truncated to the day\&. Then expression and ndistinct statistics are built on those two expressions: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE t3 ( + a timestamp +); + +INSERT INTO t3 SELECT i FROM generate_series(\*(Aq2020\-01\-01\*(Aq::timestamp, + \*(Aq2020\-12\-31\*(Aq::timestamp, + \*(Aq1 minute\*(Aq::interval) s(i); + +ANALYZE t3; + +\-\- the number of matching rows will be drastically underestimated: +EXPLAIN ANALYZE SELECT * FROM t3 + WHERE date_trunc(\*(Aqmonth\*(Aq, a) = \*(Aq2020\-01\-01\*(Aq::timestamp; + +EXPLAIN ANALYZE SELECT * FROM t3 + WHERE date_trunc(\*(Aqday\*(Aq, a) BETWEEN \*(Aq2020\-01\-01\*(Aq::timestamp + AND \*(Aq2020\-06\-30\*(Aq::timestamp; + +EXPLAIN ANALYZE SELECT date_trunc(\*(Aqmonth\*(Aq, a), date_trunc(\*(Aqday\*(Aq, a) + FROM t3 GROUP BY 1, 2; + +\-\- build ndistinct statistics on the pair of expressions (per\-expression +\-\- statistics are built automatically) +CREATE STATISTICS s3 (ndistinct) ON date_trunc(\*(Aqmonth\*(Aq, a), date_trunc(\*(Aqday\*(Aq, a) FROM t3; + +ANALYZE t3; + +\-\- now the row count estimates are more accurate: +EXPLAIN ANALYZE SELECT * FROM t3 + WHERE date_trunc(\*(Aqmonth\*(Aq, a) = \*(Aq2020\-01\-01\*(Aq::timestamp; + +EXPLAIN ANALYZE SELECT * FROM t3 + WHERE date_trunc(\*(Aqday\*(Aq, a) BETWEEN \*(Aq2020\-01\-01\*(Aq::timestamp + AND \*(Aq2020\-06\-30\*(Aq::timestamp; + +EXPLAIN ANALYZE SELECT date_trunc(\*(Aqmonth\*(Aq, a), date_trunc(\*(Aqday\*(Aq, a) + FROM t3 GROUP BY 1, 2; +.fi +.if n \{\ +.RE +.\} +.sp +Without expression and ndistinct statistics, the planner has no information about the number of distinct values for the expressions, and has to rely on default estimates\&. The equality and range conditions are assumed to have 0\&.5% selectivity, and the number of distinct values in the expression is assumed to be the same as for the column (i\&.e\&. unique)\&. This results in a significant underestimate of the row count in the first two queries\&. Moreover, the planner has no information about the relationship between the expressions, so it assumes the two +WHERE +and +GROUP BY +conditions are independent, and multiplies their selectivities together to arrive at a severe overestimate of the group count in the aggregate query\&. This is further exacerbated by the lack of accurate statistics for the expressions, forcing the planner to use a default ndistinct estimate for the expression derived from ndistinct for the column\&. With such statistics, the planner recognizes that the conditions are correlated, and arrives at much more accurate estimates\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE STATISTICS\fR +command in the SQL standard\&. +.SH "SEE ALSO" +ALTER STATISTICS (\fBALTER_STATISTICS\fR(7)), DROP STATISTICS (\fBDROP_STATISTICS\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_SUBSCRIPTION.7 b/doc/src/sgml/man7/CREATE_SUBSCRIPTION.7 new file mode 100644 index 0000000..da24c31 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_SUBSCRIPTION.7 @@ -0,0 +1,303 @@ +'\" t +.\" Title: CREATE SUBSCRIPTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE SUBSCRIPTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_SUBSCRIPTION \- define a new subscription +.SH "SYNOPSIS" +.sp +.nf +CREATE SUBSCRIPTION \fIsubscription_name\fR + CONNECTION \*(Aq\fIconninfo\fR\*(Aq + PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] + [ WITH ( \fIsubscription_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE SUBSCRIPTION\fR +adds a new logical\-replication subscription\&. The subscription name must be distinct from the name of any existing subscription in the current database\&. +.PP +A subscription represents a replication connection to the publisher\&. Hence, in addition to adding definitions in the local catalogs, this command normally creates a replication slot on the publisher\&. +.PP +A logical replication worker will be started to replicate data for the new subscription at the commit of the transaction where this command is run, unless the subscription is initially disabled\&. +.PP +Additional information about subscriptions and logical replication as a whole is available at +Section\ \&31.2 +and +Chapter\ \&31\&. +.SH "PARAMETERS" +.PP +\fIsubscription_name\fR +.RS 4 +The name of the new subscription\&. +.RE +.PP +CONNECTION \*(Aq\fIconninfo\fR\*(Aq +.RS 4 +The +libpq +connection string defining how to connect to the publisher database\&. For details see +Section\ \&34.1.1\&. +.RE +.PP +PUBLICATION \fIpublication_name\fR [, \&.\&.\&.] +.RS 4 +Names of the publications on the publisher to subscribe to\&. +.RE +.PP +WITH ( \fIsubscription_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause specifies optional parameters for a subscription\&. +.sp +The following parameters control what happens during subscription creation: +.PP +connect (boolean) +.RS 4 +Specifies whether the +\fBCREATE SUBSCRIPTION\fR +command should connect to the publisher at all\&. The default is +true\&. Setting this to +false +will force the values of +create_slot, +enabled +and +copy_data +to +false\&. (You cannot combine setting +connect +to +false +with setting +create_slot, +enabled, or +copy_data +to +true\&.) +.sp +Since no connection is made when this option is +false, no tables are subscribed, and so after you enable the subscription nothing will be replicated\&. You will need to then run +ALTER SUBSCRIPTION \&.\&.\&. REFRESH PUBLICATION +for tables to be subscribed\&. +.RE +.PP +create_slot (boolean) +.RS 4 +Specifies whether the command should create the replication slot on the publisher\&. The default is +true\&. If set to +false, you are responsible for creating the publisher\*(Aqs slot in some other way\&. +.RE +.PP +enabled (boolean) +.RS 4 +Specifies whether the subscription should be actively replicating or whether it should just be set up but not started yet\&. The default is +true\&. +.RE +.PP +slot_name (string) +.RS 4 +Name of the publisher\*(Aqs replication slot to use\&. The default is to use the name of the subscription for the slot name\&. +.sp +Setting +slot_name +to +NONE +means there will be no replication slot associated with the subscription\&. Use this when you will be creating the replication slot later manually\&. Such subscriptions must also have both +enabled +and +create_slot +set to +false\&. +.RE +.sp +The following parameters control the subscription\*(Aqs replication behavior after it has been created: +.PP +binary (boolean) +.RS 4 +Specifies whether the subscription will request the publisher to send the data in binary format (as opposed to text)\&. The default is +false\&. Even when this option is enabled, only data types having binary send and receive functions will be transferred in binary\&. +.sp +When doing cross\-version replication, it could be that the publisher has a binary send function for some data type, but the subscriber lacks a binary receive function for that type\&. In such a case, data transfer will fail, and the +binary +option cannot be used\&. +.RE +.PP +copy_data (boolean) +.RS 4 +Specifies whether to copy pre\-existing data in the publications that are being subscribed to when the replication starts\&. The default is +true\&. +.sp +If the publications contain +WHERE +clauses, it will affect what data is copied\&. Refer to the +Notes +for details\&. +.RE +.PP +streaming (boolean) +.RS 4 +Specifies whether to enable streaming of in\-progress transactions for this subscription\&. By default, all transactions are fully decoded on the publisher and only then sent to the subscriber as a whole\&. +.RE +.PP +synchronous_commit (enum) +.RS 4 +The value of this parameter overrides the +synchronous_commit +setting within this subscription\*(Aqs apply worker processes\&. The default value is +off\&. +.sp +It is safe to use +off +for logical replication: If the subscriber loses transactions because of missing synchronization, the data will be sent again from the publisher\&. +.sp +A different setting might be appropriate when doing synchronous logical replication\&. The logical replication workers report the positions of writes and flushes to the publisher, and when using synchronous replication, the publisher will wait for the actual flush\&. This means that setting +synchronous_commit +for the subscriber to +off +when the subscription is used for synchronous replication might increase the latency for +\fBCOMMIT\fR +on the publisher\&. In this scenario, it can be advantageous to set +synchronous_commit +to +local +or higher\&. +.RE +.PP +two_phase (boolean) +.RS 4 +Specifies whether two\-phase commit is enabled for this subscription\&. The default is +false\&. +.sp +When two\-phase commit is enabled, prepared transactions are sent to the subscriber at the time of +\fBPREPARE TRANSACTION\fR, and are processed as two\-phase transactions on the subscriber too\&. Otherwise, prepared transactions are sent to the subscriber only when committed, and are then processed immediately by the subscriber\&. +.sp +The implementation of two\-phase commit requires that replication has successfully finished the initial table synchronization phase\&. So even when +two_phase +is enabled for a subscription, the internal two\-phase state remains temporarily +\(lqpending\(rq +until the initialization phase completes\&. See column +subtwophasestate +of +pg_subscription +to know the actual two\-phase state\&. +.RE +.PP +disable_on_error (boolean) +.RS 4 +Specifies whether the subscription should be automatically disabled if any errors are detected by subscription workers during data replication from the publisher\&. The default is +false\&. +.RE +.RE +.SH "NOTES" +.PP +See +Section\ \&31.9 +for details on how to configure access control between the subscription and the publication instance\&. +.PP +When creating a replication slot (the default behavior), +\fBCREATE SUBSCRIPTION\fR +cannot be executed inside a transaction block\&. +.PP +Creating a subscription that connects to the same database cluster (for example, to replicate between databases in the same cluster or to replicate within the same database) will only succeed if the replication slot is not created as part of the same command\&. Otherwise, the +\fBCREATE SUBSCRIPTION\fR +call will hang\&. To make this work, create the replication slot separately (using the function +\fBpg_create_logical_replication_slot\fR +with the plugin name +pgoutput) and create the subscription using the parameter +create_slot = false\&. This is an implementation restriction that might be lifted in a future release\&. +.PP +If any table in the publication has a +WHERE +clause, rows for which the +\fIexpression\fR +evaluates to false or null will not be published\&. If the subscription has several publications in which the same table has been published with different +WHERE +clauses, a row will be published if any of the expressions (referring to that publish operation) are satisfied\&. In the case of different +WHERE +clauses, if one of the publications has no +WHERE +clause (referring to that publish operation) or the publication is declared as +FOR ALL TABLES +or +FOR TABLES IN SCHEMA, rows are always published regardless of the definition of the other expressions\&. If the subscriber is a +PostgreSQL +version before 15, then any row filtering is ignored during the initial data synchronization phase\&. For this case, the user might want to consider deleting any initially copied data that would be incompatible with subsequent filtering\&. Because initial data synchronization does not take into account the publication +publish +parameter when copying existing table data, some rows may be copied that would not be replicated using DML\&. See +Section\ \&31.2.2 +for examples\&. +.PP +Subscriptions having several publications in which the same table has been published with different column lists are not supported\&. +.PP +We allow non\-existent publications to be specified so that users can add those later\&. This means +pg_subscription +can have non\-existent publications\&. +.SH "EXAMPLES" +.PP +Create a subscription to a remote server that replicates tables in the publications +mypublication +and +insert_only +and starts replicating immediately on commit: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SUBSCRIPTION mysub + CONNECTION \*(Aqhost=192\&.168\&.1\&.50 port=5432 user=foo dbname=foodb\*(Aq + PUBLICATION mypublication, insert_only; +.fi +.if n \{\ +.RE +.\} +.PP +Create a subscription to a remote server that replicates tables in the +insert_only +publication and does not start replicating until enabled at a later time\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE SUBSCRIPTION mysub + CONNECTION \*(Aqhost=192\&.168\&.1\&.50 port=5432 user=foo dbname=foodb\*(Aq + PUBLICATION insert_only + WITH (enabled = false); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE SUBSCRIPTION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER SUBSCRIPTION (\fBALTER_SUBSCRIPTION\fR(7)), DROP SUBSCRIPTION (\fBDROP_SUBSCRIPTION\fR(7)), CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)), ALTER PUBLICATION (\fBALTER_PUBLICATION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TABLE.7 b/doc/src/sgml/man7/CREATE_TABLE.7 new file mode 100644 index 0000000..02af742 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TABLE.7 @@ -0,0 +1,1779 @@ +'\" t +.\" Title: CREATE TABLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TABLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TABLE \- define a new table +.SH "SYNOPSIS" +.sp +.nf +CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] \fItable_name\fR ( [ + { \fIcolumn_name\fR \fIdata_type\fR [ COMPRESSION \fIcompression_method\fR ] [ COLLATE \fIcollation\fR ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + | \fItable_constraint\fR + | LIKE \fIsource_table\fR [ \fIlike_option\fR \&.\&.\&. ] } + [, \&.\&.\&. ] +] ) +[ INHERITS ( \fIparent_table\fR [, \&.\&.\&. ] ) ] +[ PARTITION BY { RANGE | LIST | HASH } ( { \fIcolumn_name\fR | ( \fIexpression\fR ) } [ COLLATE \fIcollation\fR ] [ \fIopclass\fR ] [, \&.\&.\&. ] ) ] +[ USING \fImethod\fR ] +[ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) | WITHOUT OIDS ] +[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] +[ TABLESPACE \fItablespace_name\fR ] + +CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] \fItable_name\fR + OF \fItype_name\fR [ ( + { \fIcolumn_name\fR [ WITH OPTIONS ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + | \fItable_constraint\fR } + [, \&.\&.\&. ] +) ] +[ PARTITION BY { RANGE | LIST | HASH } ( { \fIcolumn_name\fR | ( \fIexpression\fR ) } [ COLLATE \fIcollation\fR ] [ \fIopclass\fR ] [, \&.\&.\&. ] ) ] +[ USING \fImethod\fR ] +[ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) | WITHOUT OIDS ] +[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] +[ TABLESPACE \fItablespace_name\fR ] + +CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] \fItable_name\fR + PARTITION OF \fIparent_table\fR [ ( + { \fIcolumn_name\fR [ WITH OPTIONS ] [ \fIcolumn_constraint\fR [ \&.\&.\&. ] ] + | \fItable_constraint\fR } + [, \&.\&.\&. ] +) ] { FOR VALUES \fIpartition_bound_spec\fR | DEFAULT } +[ PARTITION BY { RANGE | LIST | HASH } ( { \fIcolumn_name\fR | ( \fIexpression\fR ) } [ COLLATE \fIcollation\fR ] [ \fIopclass\fR ] [, \&.\&.\&. ] ) ] +[ USING \fImethod\fR ] +[ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) | WITHOUT OIDS ] +[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] +[ TABLESPACE \fItablespace_name\fR ] + +where \fIcolumn_constraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +{ NOT NULL | + NULL | + CHECK ( \fIexpression\fR ) [ NO INHERIT ] | + DEFAULT \fIdefault_expr\fR | + GENERATED ALWAYS AS ( \fIgeneration_expr\fR ) STORED | + GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( \fIsequence_options\fR ) ] | + UNIQUE [ NULLS [ NOT ] DISTINCT ] \fIindex_parameters\fR | + PRIMARY KEY \fIindex_parameters\fR | + REFERENCES \fIreftable\fR [ ( \fIrefcolumn\fR ) ] [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] + [ ON DELETE \fIreferential_action\fR ] [ ON UPDATE \fIreferential_action\fR ] } +[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] + +and \fItable_constraint\fR is: + +[ CONSTRAINT \fIconstraint_name\fR ] +{ CHECK ( \fIexpression\fR ) [ NO INHERIT ] | + UNIQUE [ NULLS [ NOT ] DISTINCT ] ( \fIcolumn_name\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR | + PRIMARY KEY ( \fIcolumn_name\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR | + EXCLUDE [ USING \fIindex_method\fR ] ( \fIexclude_element\fR WITH \fIoperator\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR [ WHERE ( \fIpredicate\fR ) ] | + FOREIGN KEY ( \fIcolumn_name\fR [, \&.\&.\&. ] ) REFERENCES \fIreftable\fR [ ( \fIrefcolumn\fR [, \&.\&.\&. ] ) ] + [ MATCH FULL | MATCH PARTIAL | MATCH SIMPLE ] [ ON DELETE \fIreferential_action\fR ] [ ON UPDATE \fIreferential_action\fR ] } +[ DEFERRABLE | NOT DEFERRABLE ] [ INITIALLY DEFERRED | INITIALLY IMMEDIATE ] + +and \fIlike_option\fR is: + +{ INCLUDING | EXCLUDING } { COMMENTS | COMPRESSION | CONSTRAINTS | DEFAULTS | GENERATED | IDENTITY | INDEXES | STATISTICS | STORAGE | ALL } + +and \fIpartition_bound_spec\fR is: + +IN ( \fIpartition_bound_expr\fR [, \&.\&.\&.] ) | +FROM ( { \fIpartition_bound_expr\fR | MINVALUE | MAXVALUE } [, \&.\&.\&.] ) + TO ( { \fIpartition_bound_expr\fR | MINVALUE | MAXVALUE } [, \&.\&.\&.] ) | +WITH ( MODULUS \fInumeric_literal\fR, REMAINDER \fInumeric_literal\fR ) + +\fIindex_parameters\fR in UNIQUE, PRIMARY KEY, and EXCLUDE constraints are: + +[ INCLUDE ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] +[ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) ] +[ USING INDEX TABLESPACE \fItablespace_name\fR ] + +\fIexclude_element\fR in an EXCLUDE constraint is: + +{ \fIcolumn_name\fR | ( \fIexpression\fR ) } [ \fIopclass\fR ] [ ASC | DESC ] [ NULLS { FIRST | LAST } ] + +\fIreferential_action\fR in a FOREIGN KEY/REFERENCES constraint is: + +{ NO ACTION | RESTRICT | CASCADE | SET NULL [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] | SET DEFAULT [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] } +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TABLE\fR +will create a new, initially empty table in the current database\&. The table will be owned by the user issuing the command\&. +.PP +If a schema name is given (for example, +CREATE TABLE myschema\&.mytable \&.\&.\&.) then the table is created in the specified schema\&. Otherwise it is created in the current schema\&. Temporary tables exist in a special schema, so a schema name cannot be given when creating a temporary table\&. The name of the table must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema\&. +.PP +\fBCREATE TABLE\fR +also automatically creates a data type that represents the composite type corresponding to one row of the table\&. Therefore, tables cannot have the same name as any existing data type in the same schema\&. +.PP +The optional constraint clauses specify constraints (tests) that new or updated rows must satisfy for an insert or update operation to succeed\&. A constraint is an SQL object that helps define the set of valid values in the table in various ways\&. +.PP +There are two ways to define constraints: table constraints and column constraints\&. A column constraint is defined as part of a column definition\&. A table constraint definition is not tied to a particular column, and it can encompass more than one column\&. Every column constraint can also be written as a table constraint; a column constraint is only a notational convenience for use when the constraint only affects one column\&. +.PP +To be able to create a table, you must have +USAGE +privilege on all column types or the type in the +OF +clause, respectively\&. +.SH "PARAMETERS" +.PP +TEMPORARY or TEMP +.RS 4 +If specified, the table is created as a temporary table\&. Temporary tables are automatically dropped at the end of a session, or optionally at the end of the current transaction (see +ON COMMIT +below)\&. The default search_path includes the temporary schema first and so identically named existing permanent tables are not chosen for new plans while the temporary table exists, unless they are referenced with schema\-qualified names\&. Any indexes created on a temporary table are automatically temporary as well\&. +.sp +The +autovacuum daemon +cannot access and therefore cannot vacuum or analyze temporary tables\&. For this reason, appropriate vacuum and analyze operations should be performed via session SQL commands\&. For example, if a temporary table is going to be used in complex queries, it is wise to run +\fBANALYZE\fR +on the temporary table after it is populated\&. +.sp +Optionally, +GLOBAL +or +LOCAL +can be written before +TEMPORARY +or +TEMP\&. This presently makes no difference in +PostgreSQL +and is deprecated; see +Compatibility +below\&. +.RE +.PP +UNLOGGED +.RS 4 +If specified, the table is created as an unlogged table\&. Data written to unlogged tables is not written to the write\-ahead log (see +Chapter\ \&30), which makes them considerably faster than ordinary tables\&. However, they are not crash\-safe: an unlogged table is automatically truncated after a crash or unclean shutdown\&. The contents of an unlogged table are also not replicated to standby servers\&. Any indexes created on an unlogged table are automatically unlogged as well\&. +.sp +If this is specified, any sequences created together with the unlogged table (for identity or serial columns) are also created as unlogged\&. +.RE +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a relation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing relation is anything like the one that would have been created\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table to be created\&. +.RE +.PP +OF \fItype_name\fR +.RS 4 +Creates a +typed table, which takes its structure from the specified composite type (name optionally schema\-qualified)\&. A typed table is tied to its type; for example the table will be dropped if the type is dropped (with +DROP TYPE \&.\&.\&. CASCADE)\&. +.sp +When a typed table is created, then the data types of the columns are determined by the underlying composite type and are not specified by the +CREATE TABLE +command\&. But the +CREATE TABLE +command can add defaults and constraints to the table and can specify storage parameters\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column to be created in the new table\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The data type of the column\&. This can include array specifiers\&. For more information on the data types supported by +PostgreSQL, refer to +Chapter\ \&8\&. +.RE +.PP +COLLATE \fIcollation\fR +.RS 4 +The +COLLATE +clause assigns a collation to the column (which must be of a collatable data type)\&. If not specified, the column data type\*(Aqs default collation is used\&. +.RE +.PP +COMPRESSION \fIcompression_method\fR +.RS 4 +The +COMPRESSION +clause sets the compression method for the column\&. Compression is supported only for variable\-width data types, and is used only when the column\*(Aqs storage mode is +main +or +extended\&. (See +ALTER TABLE (\fBALTER_TABLE\fR(7)) +for information on column storage modes\&.) Setting this property for a partitioned table has no direct effect, because such tables have no storage of their own, but the configured value will be inherited by newly\-created partitions\&. The supported compression methods are +pglz +and +lz4\&. (lz4 +is available only if +\fB\-\-with\-lz4\fR +was used when building +PostgreSQL\&.) In addition, +\fIcompression_method\fR +can be +default +to explicitly specify the default behavior, which is to consult the +default_toast_compression +setting at the time of data insertion to determine the method to use\&. +.RE +.PP +INHERITS ( \fIparent_table\fR [, \&.\&.\&. ] ) +.RS 4 +The optional +INHERITS +clause specifies a list of tables from which the new table automatically inherits all columns\&. Parent tables can be plain tables or foreign tables\&. +.sp +Use of +INHERITS +creates a persistent relationship between the new child table and its parent table(s)\&. Schema modifications to the parent(s) normally propagate to children as well, and by default the data of the child table is included in scans of the parent(s)\&. +.sp +If the same column name exists in more than one parent table, an error is reported unless the data types of the columns match in each of the parent tables\&. If there is no conflict, then the duplicate columns are merged to form a single column in the new table\&. If the column name list of the new table contains a column name that is also inherited, the data type must likewise match the inherited column(s), and the column definitions are merged into one\&. If the new table explicitly specifies a default value for the column, this default overrides any defaults from inherited declarations of the column\&. Otherwise, any parents that specify default values for the column must all specify the same default, or an error will be reported\&. +.sp +CHECK +constraints are merged in essentially the same way as columns: if multiple parent tables and/or the new table definition contain identically\-named +CHECK +constraints, these constraints must all have the same check expression, or an error will be reported\&. Constraints having the same name and expression will be merged into one copy\&. A constraint marked +NO INHERIT +in a parent will not be considered\&. Notice that an unnamed +CHECK +constraint in the new table will never be merged, since a unique name will always be chosen for it\&. +.sp +Column +STORAGE +settings are also copied from parent tables\&. +.sp +If a column in the parent table is an identity column, that property is not inherited\&. A column in the child table can be declared identity column if desired\&. +.RE +.PP +PARTITION BY { RANGE | LIST | HASH } ( { \fIcolumn_name\fR | ( \fIexpression\fR ) } [ \fIopclass\fR ] [, \&.\&.\&.] ) +.RS 4 +The optional +PARTITION BY +clause specifies a strategy of partitioning the table\&. The table thus created is called a +partitioned +table\&. The parenthesized list of columns or expressions forms the +partition key +for the table\&. When using range or hash partitioning, the partition key can include multiple columns or expressions (up to 32, but this limit can be altered when building +PostgreSQL), but for list partitioning, the partition key must consist of a single column or expression\&. +.sp +Range and list partitioning require a btree operator class, while hash partitioning requires a hash operator class\&. If no operator class is specified explicitly, the default operator class of the appropriate type will be used; if no default operator class exists, an error will be raised\&. When hash partitioning is used, the operator class used must implement support function 2 (see +Section\ \&38.16.3 +for details)\&. +.sp +A partitioned table is divided into sub\-tables (called partitions), which are created using separate +CREATE TABLE +commands\&. The partitioned table is itself empty\&. A data row inserted into the table is routed to a partition based on the value of columns or expressions in the partition key\&. If no existing partition matches the values in the new row, an error will be reported\&. +.sp +Partitioned tables do not support +EXCLUDE +constraints; however, you can define these constraints on individual partitions\&. +.sp +See +Section\ \&5.11 +for more discussion on table partitioning\&. +.RE +.PP +PARTITION OF \fIparent_table\fR { FOR VALUES \fIpartition_bound_spec\fR | DEFAULT } +.RS 4 +Creates the table as a +partition +of the specified parent table\&. The table can be created either as a partition for specific values using +FOR VALUES +or as a default partition using +DEFAULT\&. Any indexes, constraints and user\-defined row\-level triggers that exist in the parent table are cloned on the new partition\&. +.sp +The +\fIpartition_bound_spec\fR +must correspond to the partitioning method and partition key of the parent table, and must not overlap with any existing partition of that parent\&. The form with +IN +is used for list partitioning, the form with +FROM +and +TO +is used for range partitioning, and the form with +WITH +is used for hash partitioning\&. +.sp +\fIpartition_bound_expr\fR +is any variable\-free expression (subqueries, window functions, aggregate functions, and set\-returning functions are not allowed)\&. Its data type must match the data type of the corresponding partition key column\&. The expression is evaluated once at table creation time, so it can even contain volatile expressions such as +\fBCURRENT_TIMESTAMP\fR\&. +.sp +When creating a list partition, +NULL +can be specified to signify that the partition allows the partition key column to be null\&. However, there cannot be more than one such list partition for a given parent table\&. +NULL +cannot be specified for range partitions\&. +.sp +When creating a range partition, the lower bound specified with +FROM +is an inclusive bound, whereas the upper bound specified with +TO +is an exclusive bound\&. That is, the values specified in the +FROM +list are valid values of the corresponding partition key columns for this partition, whereas those in the +TO +list are not\&. Note that this statement must be understood according to the rules of row\-wise comparison (Section\ \&9.24.5)\&. For example, given +PARTITION BY RANGE (x,y), a partition bound +FROM (1, 2) TO (3, 4) +allows +x=1 +with any +y>=2, +x=2 +with any non\-null +y, and +x=3 +with any +y<4\&. +.sp +The special values +MINVALUE +and +MAXVALUE +may be used when creating a range partition to indicate that there is no lower or upper bound on the column\*(Aqs value\&. For example, a partition defined using +FROM (MINVALUE) TO (10) +allows any values less than 10, and a partition defined using +FROM (10) TO (MAXVALUE) +allows any values greater than or equal to 10\&. +.sp +When creating a range partition involving more than one column, it can also make sense to use +MAXVALUE +as part of the lower bound, and +MINVALUE +as part of the upper bound\&. For example, a partition defined using +FROM (0, MAXVALUE) TO (10, MAXVALUE) +allows any rows where the first partition key column is greater than 0 and less than or equal to 10\&. Similarly, a partition defined using +FROM (\*(Aqa\*(Aq, MINVALUE) TO (\*(Aqb\*(Aq, MINVALUE) +allows any rows where the first partition key column starts with "a"\&. +.sp +Note that if +MINVALUE +or +MAXVALUE +is used for one column of a partitioning bound, the same value must be used for all subsequent columns\&. For example, +(10, MINVALUE, 0) +is not a valid bound; you should write +(10, MINVALUE, MINVALUE)\&. +.sp +Also note that some element types, such as +timestamp, have a notion of "infinity", which is just another value that can be stored\&. This is different from +MINVALUE +and +MAXVALUE, which are not real values that can be stored, but rather they are ways of saying that the value is unbounded\&. +MAXVALUE +can be thought of as being greater than any other value, including "infinity" and +MINVALUE +as being less than any other value, including "minus infinity"\&. Thus the range +FROM (\*(Aqinfinity\*(Aq) TO (MAXVALUE) +is not an empty range; it allows precisely one value to be stored \(em "infinity"\&. +.sp +If +DEFAULT +is specified, the table will be created as the default partition of the parent table\&. This option is not available for hash\-partitioned tables\&. A partition key value not fitting into any other partition of the given parent will be routed to the default partition\&. +.sp +When a table has an existing +DEFAULT +partition and a new partition is added to it, the default partition must be scanned to verify that it does not contain any rows which properly belong in the new partition\&. If the default partition contains a large number of rows, this may be slow\&. The scan will be skipped if the default partition is a foreign table or if it has a constraint which proves that it cannot contain rows which should be placed in the new partition\&. +.sp +When creating a hash partition, a modulus and remainder must be specified\&. The modulus must be a positive integer, and the remainder must be a non\-negative integer less than the modulus\&. Typically, when initially setting up a hash\-partitioned table, you should choose a modulus equal to the number of partitions and assign every table the same modulus and a different remainder (see examples, below)\&. However, it is not required that every partition have the same modulus, only that every modulus which occurs among the partitions of a hash\-partitioned table is a factor of the next larger modulus\&. This allows the number of partitions to be increased incrementally without needing to move all the data at once\&. For example, suppose you have a hash\-partitioned table with 8 partitions, each of which has modulus 8, but find it necessary to increase the number of partitions to 16\&. You can detach one of the modulus\-8 partitions, create two new modulus\-16 partitions covering the same portion of the key space (one with a remainder equal to the remainder of the detached partition, and the other with a remainder equal to that value plus 8), and repopulate them with data\&. You can then repeat this \-\- perhaps at a later time \-\- for each modulus\-8 partition until none remain\&. While this may still involve a large amount of data movement at each step, it is still better than having to create a whole new table and move all the data at once\&. +.sp +A partition must have the same column names and types as the partitioned table to which it belongs\&. Modifications to the column names or types of a partitioned table will automatically propagate to all partitions\&. +CHECK +constraints will be inherited automatically by every partition, but an individual partition may specify additional +CHECK +constraints; additional constraints with the same name and condition as in the parent will be merged with the parent constraint\&. Defaults may be specified separately for each partition\&. But note that a partition\*(Aqs default value is not applied when inserting a tuple through a partitioned table\&. +.sp +Rows inserted into a partitioned table will be automatically routed to the correct partition\&. If no suitable partition exists, an error will occur\&. +.sp +Operations such as +\fBTRUNCATE\fR +which normally affect a table and all of its inheritance children will cascade to all partitions, but may also be performed on an individual partition\&. +.sp +Note that creating a partition using +PARTITION OF +requires taking an +ACCESS EXCLUSIVE +lock on the parent partitioned table\&. Likewise, dropping a partition with +\fBDROP TABLE\fR +requires taking an +ACCESS EXCLUSIVE +lock on the parent table\&. It is possible to use +\fBALTER TABLE ATTACH/DETACH PARTITION\fR +to perform these operations with a weaker lock, thus reducing interference with concurrent operations on the partitioned table\&. +.RE +.PP +LIKE \fIsource_table\fR [ \fIlike_option\fR \&.\&.\&. ] +.RS 4 +The +LIKE +clause specifies a table from which the new table automatically copies all column names, their data types, and their not\-null constraints\&. +.sp +Unlike +INHERITS, the new table and original table are completely decoupled after creation is complete\&. Changes to the original table will not be applied to the new table, and it is not possible to include data of the new table in scans of the original table\&. +.sp +Also unlike +INHERITS, columns and constraints copied by +LIKE +are not merged with similarly named columns and constraints\&. If the same name is specified explicitly or in another +LIKE +clause, an error is signaled\&. +.sp +The optional +\fIlike_option\fR +clauses specify which additional properties of the original table to copy\&. Specifying +INCLUDING +copies the property, specifying +EXCLUDING +omits the property\&. +EXCLUDING +is the default\&. If multiple specifications are made for the same kind of object, the last one is used\&. The available options are: +.PP +INCLUDING COMMENTS +.RS 4 +Comments for the copied columns, constraints, and indexes will be copied\&. The default behavior is to exclude comments, resulting in the copied columns and constraints in the new table having no comments\&. +.RE +.PP +INCLUDING COMPRESSION +.RS 4 +Compression method of the columns will be copied\&. The default behavior is to exclude compression methods, resulting in columns having the default compression method\&. +.RE +.PP +INCLUDING CONSTRAINTS +.RS 4 +CHECK +constraints will be copied\&. No distinction is made between column constraints and table constraints\&. Not\-null constraints are always copied to the new table\&. +.RE +.PP +INCLUDING DEFAULTS +.RS 4 +Default expressions for the copied column definitions will be copied\&. Otherwise, default expressions are not copied, resulting in the copied columns in the new table having null defaults\&. Note that copying defaults that call database\-modification functions, such as +\fBnextval\fR, may create a functional linkage between the original and new tables\&. +.RE +.PP +INCLUDING GENERATED +.RS 4 +Any generation expressions of copied column definitions will be copied\&. By default, new columns will be regular base columns\&. +.RE +.PP +INCLUDING IDENTITY +.RS 4 +Any identity specifications of copied column definitions will be copied\&. A new sequence is created for each identity column of the new table, separate from the sequences associated with the old table\&. +.RE +.PP +INCLUDING INDEXES +.RS 4 +Indexes, +PRIMARY KEY, +UNIQUE, and +EXCLUDE +constraints on the original table will be created on the new table\&. Names for the new indexes and constraints are chosen according to the default rules, regardless of how the originals were named\&. (This behavior avoids possible duplicate\-name failures for the new indexes\&.) +.RE +.PP +INCLUDING STATISTICS +.RS 4 +Extended statistics are copied to the new table\&. +.RE +.PP +INCLUDING STORAGE +.RS 4 +STORAGE +settings for the copied column definitions will be copied\&. The default behavior is to exclude +STORAGE +settings, resulting in the copied columns in the new table having type\-specific default settings\&. For more on +STORAGE +settings, see +Section\ \&73.2\&. +.RE +.PP +INCLUDING ALL +.RS 4 +INCLUDING ALL +is an abbreviated form selecting all the available individual options\&. (It could be useful to write individual +EXCLUDING +clauses after +INCLUDING ALL +to select all but some specific options\&.) +.RE +.sp +The +LIKE +clause can also be used to copy column definitions from views, foreign tables, or composite types\&. Inapplicable options (e\&.g\&., +INCLUDING INDEXES +from a view) are ignored\&. +.RE +.PP +CONSTRAINT \fIconstraint_name\fR +.RS 4 +An optional name for a column or table constraint\&. If the constraint is violated, the constraint name is present in error messages, so constraint names like +col must be positive +can be used to communicate helpful constraint information to client applications\&. (Double\-quotes are needed to specify constraint names that contain spaces\&.) If a constraint name is not specified, the system generates a name\&. +.RE +.PP +NOT NULL +.RS 4 +The column is not allowed to contain null values\&. +.RE +.PP +NULL +.RS 4 +The column is allowed to contain null values\&. This is the default\&. +.sp +This clause is only provided for compatibility with non\-standard SQL databases\&. Its use is discouraged in new applications\&. +.RE +.PP +CHECK ( \fIexpression\fR ) [ NO INHERIT ] +.RS 4 +The +CHECK +clause specifies an expression producing a Boolean result which new or updated rows must satisfy for an insert or update operation to succeed\&. Expressions evaluating to TRUE or UNKNOWN succeed\&. Should any row of an insert or update operation produce a FALSE result, an error exception is raised and the insert or update does not alter the database\&. A check constraint specified as a column constraint should reference that column\*(Aqs value only, while an expression appearing in a table constraint can reference multiple columns\&. +.sp +Currently, +CHECK +expressions cannot contain subqueries nor refer to variables other than columns of the current row (see +Section\ \&5.4.1)\&. The system column +tableoid +may be referenced, but not any other system column\&. +.sp +A constraint marked with +NO INHERIT +will not propagate to child tables\&. +.sp +When a table has multiple +CHECK +constraints, they will be tested for each row in alphabetical order by name, after checking +NOT NULL +constraints\&. (PostgreSQL +versions before 9\&.5 did not honor any particular firing order for +CHECK +constraints\&.) +.RE +.PP +DEFAULT \fIdefault_expr\fR +.RS 4 +The +DEFAULT +clause assigns a default data value for the column whose column definition it appears within\&. The value is any variable\-free expression (in particular, cross\-references to other columns in the current table are not allowed)\&. Subqueries are not allowed either\&. The data type of the default expression must match the data type of the column\&. +.sp +The default expression will be used in any insert operation that does not specify a value for the column\&. If there is no default for a column, then the default is null\&. +.RE +.PP +GENERATED ALWAYS AS ( \fIgeneration_expr\fR ) STORED +.RS 4 +This clause creates the column as a +generated column\&. The column cannot be written to, and when read the result of the specified expression will be returned\&. +.sp +The keyword +STORED +is required to signify that the column will be computed on write and will be stored on disk\&. +.sp +The generation expression can refer to other columns in the table, but not other generated columns\&. Any functions and operators used must be immutable\&. References to other tables are not allowed\&. +.RE +.PP +GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY [ ( \fIsequence_options\fR ) ] +.RS 4 +This clause creates the column as an +identity column\&. It will have an implicit sequence attached to it and the column in new rows will automatically have values from the sequence assigned to it\&. Such a column is implicitly +NOT NULL\&. +.sp +The clauses +ALWAYS +and +BY DEFAULT +determine how explicitly user\-specified values are handled in +\fBINSERT\fR +and +\fBUPDATE\fR +commands\&. +.sp +In an +\fBINSERT\fR +command, if +ALWAYS +is selected, a user\-specified value is only accepted if the +\fBINSERT\fR +statement specifies +OVERRIDING SYSTEM VALUE\&. If +BY DEFAULT +is selected, then the user\-specified value takes precedence\&. See +\fBINSERT\fR(7) +for details\&. (In the +\fBCOPY\fR +command, user\-specified values are always used regardless of this setting\&.) +.sp +In an +\fBUPDATE\fR +command, if +ALWAYS +is selected, any update of the column to any value other than +DEFAULT +will be rejected\&. If +BY DEFAULT +is selected, the column can be updated normally\&. (There is no +OVERRIDING +clause for the +\fBUPDATE\fR +command\&.) +.sp +The optional +\fIsequence_options\fR +clause can be used to override the options of the sequence\&. See +CREATE SEQUENCE (\fBCREATE_SEQUENCE\fR(7)) +for details\&. +.RE +.PP +UNIQUE [ NULLS [ NOT ] DISTINCT ] (column constraint) +.br +UNIQUE [ NULLS [ NOT ] DISTINCT ] ( \fIcolumn_name\fR [, \&.\&.\&. ] ) [ INCLUDE ( \fIcolumn_name\fR [, \&.\&.\&.]) ] (table constraint) +.RS 4 +The +UNIQUE +constraint specifies that a group of one or more columns of a table can contain only unique values\&. The behavior of a unique table constraint is the same as that of a unique column constraint, with the additional capability to span multiple columns\&. The constraint therefore enforces that any two rows must differ in at least one of these columns\&. +.sp +For the purpose of a unique constraint, null values are not considered equal, unless +NULLS NOT DISTINCT +is specified\&. +.sp +Each unique constraint should name a set of columns that is different from the set of columns named by any other unique or primary key constraint defined for the table\&. (Otherwise, redundant unique constraints will be discarded\&.) +.sp +When establishing a unique constraint for a multi\-level partition hierarchy, all the columns in the partition key of the target partitioned table, as well as those of all its descendant partitioned tables, must be included in the constraint definition\&. +.sp +Adding a unique constraint will automatically create a unique btree index on the column or group of columns used in the constraint\&. +.sp +The optional +INCLUDE +clause adds to that index one or more columns that are simply +\(lqpayload\(rq: uniqueness is not enforced on them, and the index cannot be searched on the basis of those columns\&. However they can be retrieved by an index\-only scan\&. Note that although the constraint is not enforced on included columns, it still depends on them\&. Consequently, some operations on such columns (e\&.g\&., +DROP COLUMN) can cause cascaded constraint and index deletion\&. +.RE +.PP +PRIMARY KEY (column constraint) +.br +PRIMARY KEY ( \fIcolumn_name\fR [, \&.\&.\&. ] ) [ INCLUDE ( \fIcolumn_name\fR [, \&.\&.\&.]) ] (table constraint) +.RS 4 +The +PRIMARY KEY +constraint specifies that a column or columns of a table can contain only unique (non\-duplicate), nonnull values\&. Only one primary key can be specified for a table, whether as a column constraint or a table constraint\&. +.sp +The primary key constraint should name a set of columns that is different from the set of columns named by any unique constraint defined for the same table\&. (Otherwise, the unique constraint is redundant and will be discarded\&.) +.sp +PRIMARY KEY +enforces the same data constraints as a combination of +UNIQUE +and +NOT NULL\&. However, identifying a set of columns as the primary key also provides metadata about the design of the schema, since a primary key implies that other tables can rely on this set of columns as a unique identifier for rows\&. +.sp +When placed on a partitioned table, +PRIMARY KEY +constraints share the restrictions previously described for +UNIQUE +constraints\&. +.sp +Adding a +PRIMARY KEY +constraint will automatically create a unique btree index on the column or group of columns used in the constraint\&. +.sp +The optional +INCLUDE +clause adds to that index one or more columns that are simply +\(lqpayload\(rq: uniqueness is not enforced on them, and the index cannot be searched on the basis of those columns\&. However they can be retrieved by an index\-only scan\&. Note that although the constraint is not enforced on included columns, it still depends on them\&. Consequently, some operations on such columns (e\&.g\&., +DROP COLUMN) can cause cascaded constraint and index deletion\&. +.RE +.PP +EXCLUDE [ USING \fIindex_method\fR ] ( \fIexclude_element\fR WITH \fIoperator\fR [, \&.\&.\&. ] ) \fIindex_parameters\fR [ WHERE ( \fIpredicate\fR ) ] +.RS 4 +The +EXCLUDE +clause defines an exclusion constraint, which guarantees that if any two rows are compared on the specified column(s) or expression(s) using the specified operator(s), not all of these comparisons will return +TRUE\&. If all of the specified operators test for equality, this is equivalent to a +UNIQUE +constraint, although an ordinary unique constraint will be faster\&. However, exclusion constraints can specify constraints that are more general than simple equality\&. For example, you can specify a constraint that no two rows in the table contain overlapping circles (see +Section\ \&8.8) by using the +&& +operator\&. +.sp +Exclusion constraints are implemented using an index, so each specified operator must be associated with an appropriate operator class (see +Section\ \&11.10) for the index access method +\fIindex_method\fR\&. The operators are required to be commutative\&. Each +\fIexclude_element\fR +can optionally specify an operator class and/or ordering options; these are described fully under +CREATE INDEX (\fBCREATE_INDEX\fR(7))\&. +.sp +The access method must support +amgettuple +(see +Chapter\ \&64); at present this means +GIN +cannot be used\&. Although it\*(Aqs allowed, there is little point in using B\-tree or hash indexes with an exclusion constraint, because this does nothing that an ordinary unique constraint doesn\*(Aqt do better\&. So in practice the access method will always be +GiST +or +SP\-GiST\&. +.sp +The +\fIpredicate\fR +allows you to specify an exclusion constraint on a subset of the table; internally this creates a partial index\&. Note that parentheses are required around the predicate\&. +.RE +.PP +REFERENCES \fIreftable\fR [ ( \fIrefcolumn\fR ) ] [ MATCH \fImatchtype\fR ] [ ON DELETE \fIreferential_action\fR ] [ ON UPDATE \fIreferential_action\fR ] (column constraint) +.br +FOREIGN KEY ( \fIcolumn_name\fR [, \&.\&.\&. ] ) REFERENCES \fIreftable\fR [ ( \fIrefcolumn\fR [, \&.\&.\&. ] ) ] [ MATCH \fImatchtype\fR ] [ ON DELETE \fIreferential_action\fR ] [ ON UPDATE \fIreferential_action\fR ] (table constraint) +.RS 4 +These clauses specify a foreign key constraint, which requires that a group of one or more columns of the new table must only contain values that match values in the referenced column(s) of some row of the referenced table\&. If the +\fIrefcolumn\fR +list is omitted, the primary key of the +\fIreftable\fR +is used\&. The referenced columns must be the columns of a non\-deferrable unique or primary key constraint in the referenced table\&. The user must have +REFERENCES +permission on the referenced table (either the whole table, or the specific referenced columns)\&. The addition of a foreign key constraint requires a +SHARE ROW EXCLUSIVE +lock on the referenced table\&. Note that foreign key constraints cannot be defined between temporary tables and permanent tables\&. +.sp +A value inserted into the referencing column(s) is matched against the values of the referenced table and referenced columns using the given match type\&. There are three match types: +MATCH FULL, +MATCH PARTIAL, and +MATCH SIMPLE +(which is the default)\&. +MATCH FULL +will not allow one column of a multicolumn foreign key to be null unless all foreign key columns are null; if they are all null, the row is not required to have a match in the referenced table\&. +MATCH SIMPLE +allows any of the foreign key columns to be null; if any of them are null, the row is not required to have a match in the referenced table\&. +MATCH PARTIAL +is not yet implemented\&. (Of course, +NOT NULL +constraints can be applied to the referencing column(s) to prevent these cases from arising\&.) +.sp +In addition, when the data in the referenced columns is changed, certain actions are performed on the data in this table\*(Aqs columns\&. The +ON DELETE +clause specifies the action to perform when a referenced row in the referenced table is being deleted\&. Likewise, the +ON UPDATE +clause specifies the action to perform when a referenced column in the referenced table is being updated to a new value\&. If the row is updated, but the referenced column is not actually changed, no action is done\&. Referential actions other than the +NO ACTION +check cannot be deferred, even if the constraint is declared deferrable\&. There are the following possible actions for each clause: +.PP +NO ACTION +.RS 4 +Produce an error indicating that the deletion or update would create a foreign key constraint violation\&. If the constraint is deferred, this error will be produced at constraint check time if there still exist any referencing rows\&. This is the default action\&. +.RE +.PP +RESTRICT +.RS 4 +Produce an error indicating that the deletion or update would create a foreign key constraint violation\&. This is the same as +NO ACTION +except that the check is not deferrable\&. +.RE +.PP +CASCADE +.RS 4 +Delete any rows referencing the deleted row, or update the values of the referencing column(s) to the new values of the referenced columns, respectively\&. +.RE +.PP +SET NULL [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] +.RS 4 +Set all of the referencing columns, or a specified subset of the referencing columns, to null\&. A subset of columns can only be specified for +ON DELETE +actions\&. +.RE +.PP +SET DEFAULT [ ( \fIcolumn_name\fR [, \&.\&.\&. ] ) ] +.RS 4 +Set all of the referencing columns, or a specified subset of the referencing columns, to their default values\&. A subset of columns can only be specified for +ON DELETE +actions\&. (There must be a row in the referenced table matching the default values, if they are not null, or the operation will fail\&.) +.RE +.sp +If the referenced column(s) are changed frequently, it might be wise to add an index to the referencing column(s) so that referential actions associated with the foreign key constraint can be performed more efficiently\&. +.RE +.PP +DEFERRABLE +.br +NOT DEFERRABLE +.RS 4 +This controls whether the constraint can be deferred\&. A constraint that is not deferrable will be checked immediately after every command\&. Checking of constraints that are deferrable can be postponed until the end of the transaction (using the +\fBSET CONSTRAINTS\fR +command)\&. +NOT DEFERRABLE +is the default\&. Currently, only +UNIQUE, +PRIMARY KEY, +EXCLUDE, and +REFERENCES +(foreign key) constraints accept this clause\&. +NOT NULL +and +CHECK +constraints are not deferrable\&. Note that deferrable constraints cannot be used as conflict arbitrators in an +\fBINSERT\fR +statement that includes an +ON CONFLICT DO UPDATE +clause\&. +.RE +.PP +INITIALLY IMMEDIATE +.br +INITIALLY DEFERRED +.RS 4 +If a constraint is deferrable, this clause specifies the default time to check the constraint\&. If the constraint is +INITIALLY IMMEDIATE, it is checked after each statement\&. This is the default\&. If the constraint is +INITIALLY DEFERRED, it is checked only at the end of the transaction\&. The constraint check time can be altered with the +\fBSET CONSTRAINTS\fR +command\&. +.RE +.PP +USING \fImethod\fR +.RS 4 +This optional clause specifies the table access method to use to store the contents for the new table; the method needs be an access method of type +TABLE\&. See +Chapter\ \&63 +for more information\&. If this option is not specified, the default table access method is chosen for the new table\&. See +default_table_access_method +for more information\&. +.RE +.PP +WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause specifies optional storage parameters for a table or index; see +Storage Parameters +below for more information\&. For backward\-compatibility the +WITH +clause for a table can also include +OIDS=FALSE +to specify that rows of the new table should not contain OIDs (object identifiers), +OIDS=TRUE +is not supported anymore\&. +.RE +.PP +WITHOUT OIDS +.RS 4 +This is backward\-compatible syntax for declaring a table +WITHOUT OIDS, creating a table +WITH OIDS +is not supported anymore\&. +.RE +.PP +ON COMMIT +.RS 4 +The behavior of temporary tables at the end of a transaction block can be controlled using +ON COMMIT\&. The three options are: +.PP +PRESERVE ROWS +.RS 4 +No special action is taken at the ends of transactions\&. This is the default behavior\&. +.RE +.PP +DELETE ROWS +.RS 4 +All rows in the temporary table will be deleted at the end of each transaction block\&. Essentially, an automatic +\fBTRUNCATE\fR +is done at each commit\&. When used on a partitioned table, this is not cascaded to its partitions\&. +.RE +.PP +DROP +.RS 4 +The temporary table will be dropped at the end of the current transaction block\&. When used on a partitioned table, this action drops its partitions and when used on tables with inheritance children, it drops the dependent children\&. +.RE +.RE +.PP +TABLESPACE \fItablespace_name\fR +.RS 4 +The +\fItablespace_name\fR +is the name of the tablespace in which the new table is to be created\&. If not specified, +default_tablespace +is consulted, or +temp_tablespaces +if the table is temporary\&. For partitioned tables, since no storage is required for the table itself, the tablespace specified overrides +default_tablespace +as the default tablespace to use for any newly created partitions when no other tablespace is explicitly specified\&. +.RE +.PP +USING INDEX TABLESPACE \fItablespace_name\fR +.RS 4 +This clause allows selection of the tablespace in which the index associated with a +UNIQUE, +PRIMARY KEY, or +EXCLUDE +constraint will be created\&. If not specified, +default_tablespace +is consulted, or +temp_tablespaces +if the table is temporary\&. +.RE +.SS "Storage Parameters" +.PP +The +WITH +clause can specify +storage parameters +for tables, and for indexes associated with a +UNIQUE, +PRIMARY KEY, or +EXCLUDE +constraint\&. Storage parameters for indexes are documented in +CREATE INDEX (\fBCREATE_INDEX\fR(7))\&. The storage parameters currently available for tables are listed below\&. For many of these parameters, as shown, there is an additional parameter with the same name prefixed with +toast\&., which controls the behavior of the table\*(Aqs secondary +TOAST +table, if any (see +Section\ \&73.2 +for more information about TOAST)\&. If a table parameter value is set and the equivalent +toast\&. +parameter is not, the TOAST table will use the table\*(Aqs parameter value\&. Specifying these parameters for partitioned tables is not supported, but you may specify them for individual leaf partitions\&. +.PP +\fIfillfactor\fR (integer) +.RS 4 +The fillfactor for a table is a percentage between 10 and 100\&. 100 (complete packing) is the default\&. When a smaller fillfactor is specified, +\fBINSERT\fR +operations pack table pages only to the indicated percentage; the remaining space on each page is reserved for updating rows on that page\&. This gives +\fBUPDATE\fR +a chance to place the updated copy of a row on the same page as the original, which is more efficient than placing it on a different page, and makes +heap\-only tuple updates +more likely\&. For a table whose entries are never updated, complete packing is the best choice, but in heavily updated tables smaller fillfactors are appropriate\&. This parameter cannot be set for TOAST tables\&. +.RE +.PP +toast_tuple_target (integer) +.RS 4 +The toast_tuple_target specifies the minimum tuple length required before we try to compress and/or move long column values into TOAST tables, and is also the target length we try to reduce the length below once toasting begins\&. This affects columns marked as External (for move), Main (for compression), or Extended (for both) and applies only to new tuples\&. There is no effect on existing rows\&. By default this parameter is set to allow at least 4 tuples per block, which with the default block size will be 2040 bytes\&. Valid values are between 128 bytes and the (block size \- header), by default 8160 bytes\&. Changing this value may not be useful for very short or very long rows\&. Note that the default setting is often close to optimal, and it is possible that setting this parameter could have negative effects in some cases\&. This parameter cannot be set for TOAST tables\&. +.RE +.PP +parallel_workers (integer) +.RS 4 +This sets the number of workers that should be used to assist a parallel scan of this table\&. If not set, the system will determine a value based on the relation size\&. The actual number of workers chosen by the planner or by utility statements that use parallel scans may be less, for example due to the setting of +max_worker_processes\&. +.RE +.PP +autovacuum_enabled, toast\&.autovacuum_enabled (boolean) +.RS 4 +Enables or disables the autovacuum daemon for a particular table\&. If true, the autovacuum daemon will perform automatic +\fBVACUUM\fR +and/or +\fBANALYZE\fR +operations on this table following the rules discussed in +Section\ \&25.1.6\&. If false, this table will not be autovacuumed, except to prevent transaction ID wraparound\&. See +Section\ \&25.1.5 +for more about wraparound prevention\&. Note that the autovacuum daemon does not run at all (except to prevent transaction ID wraparound) if the +autovacuum +parameter is false; setting individual tables\*(Aq storage parameters does not override that\&. Therefore there is seldom much point in explicitly setting this storage parameter to +true, only to +false\&. +.RE +.PP +vacuum_index_cleanup, toast\&.vacuum_index_cleanup (enum) +.RS 4 +Forces or disables index cleanup when +\fBVACUUM\fR +is run on this table\&. The default value is +AUTO\&. With +OFF, index cleanup is disabled, with +ON +it is enabled, and with +AUTO +a decision is made dynamically, each time +\fBVACUUM\fR +runs\&. The dynamic behavior allows +\fBVACUUM\fR +to avoid needlessly scanning indexes to remove very few dead tuples\&. Forcibly disabling all index cleanup can speed up +\fBVACUUM\fR +very significantly, but may also lead to severely bloated indexes if table modifications are frequent\&. The +INDEX_CLEANUP +parameter of +\fBVACUUM\fR, if specified, overrides the value of this option\&. +.RE +.PP +vacuum_truncate, toast\&.vacuum_truncate (boolean) +.RS 4 +Enables or disables vacuum to try to truncate off any empty pages at the end of this table\&. The default value is +true\&. If +true, +\fBVACUUM\fR +and autovacuum do the truncation and the disk space for the truncated pages is returned to the operating system\&. Note that the truncation requires +ACCESS EXCLUSIVE +lock on the table\&. The +TRUNCATE +parameter of +\fBVACUUM\fR, if specified, overrides the value of this option\&. +.RE +.PP +autovacuum_vacuum_threshold, toast\&.autovacuum_vacuum_threshold (integer) +.RS 4 +Per\-table value for +autovacuum_vacuum_threshold +parameter\&. +.RE +.PP +autovacuum_vacuum_scale_factor, toast\&.autovacuum_vacuum_scale_factor (floating point) +.RS 4 +Per\-table value for +autovacuum_vacuum_scale_factor +parameter\&. +.RE +.PP +autovacuum_vacuum_insert_threshold, toast\&.autovacuum_vacuum_insert_threshold (integer) +.RS 4 +Per\-table value for +autovacuum_vacuum_insert_threshold +parameter\&. The special value of \-1 may be used to disable insert vacuums on the table\&. +.RE +.PP +autovacuum_vacuum_insert_scale_factor, toast\&.autovacuum_vacuum_insert_scale_factor (floating point) +.RS 4 +Per\-table value for +autovacuum_vacuum_insert_scale_factor +parameter\&. +.RE +.PP +autovacuum_analyze_threshold (integer) +.RS 4 +Per\-table value for +autovacuum_analyze_threshold +parameter\&. +.RE +.PP +autovacuum_analyze_scale_factor (floating point) +.RS 4 +Per\-table value for +autovacuum_analyze_scale_factor +parameter\&. +.RE +.PP +autovacuum_vacuum_cost_delay, toast\&.autovacuum_vacuum_cost_delay (floating point) +.RS 4 +Per\-table value for +autovacuum_vacuum_cost_delay +parameter\&. +.RE +.PP +autovacuum_vacuum_cost_limit, toast\&.autovacuum_vacuum_cost_limit (integer) +.RS 4 +Per\-table value for +autovacuum_vacuum_cost_limit +parameter\&. +.RE +.PP +autovacuum_freeze_min_age, toast\&.autovacuum_freeze_min_age (integer) +.RS 4 +Per\-table value for +vacuum_freeze_min_age +parameter\&. Note that autovacuum will ignore per\-table +autovacuum_freeze_min_age +parameters that are larger than half the system\-wide +autovacuum_freeze_max_age +setting\&. +.RE +.PP +autovacuum_freeze_max_age, toast\&.autovacuum_freeze_max_age (integer) +.RS 4 +Per\-table value for +autovacuum_freeze_max_age +parameter\&. Note that autovacuum will ignore per\-table +autovacuum_freeze_max_age +parameters that are larger than the system\-wide setting (it can only be set smaller)\&. +.RE +.PP +autovacuum_freeze_table_age, toast\&.autovacuum_freeze_table_age (integer) +.RS 4 +Per\-table value for +vacuum_freeze_table_age +parameter\&. +.RE +.PP +autovacuum_multixact_freeze_min_age, toast\&.autovacuum_multixact_freeze_min_age (integer) +.RS 4 +Per\-table value for +vacuum_multixact_freeze_min_age +parameter\&. Note that autovacuum will ignore per\-table +autovacuum_multixact_freeze_min_age +parameters that are larger than half the system\-wide +autovacuum_multixact_freeze_max_age +setting\&. +.RE +.PP +autovacuum_multixact_freeze_max_age, toast\&.autovacuum_multixact_freeze_max_age (integer) +.RS 4 +Per\-table value for +autovacuum_multixact_freeze_max_age +parameter\&. Note that autovacuum will ignore per\-table +autovacuum_multixact_freeze_max_age +parameters that are larger than the system\-wide setting (it can only be set smaller)\&. +.RE +.PP +autovacuum_multixact_freeze_table_age, toast\&.autovacuum_multixact_freeze_table_age (integer) +.RS 4 +Per\-table value for +vacuum_multixact_freeze_table_age +parameter\&. +.RE +.PP +log_autovacuum_min_duration, toast\&.log_autovacuum_min_duration (integer) +.RS 4 +Per\-table value for +log_autovacuum_min_duration +parameter\&. +.RE +.PP +user_catalog_table (boolean) +.RS 4 +Declare the table as an additional catalog table for purposes of logical replication\&. See +Section\ \&49.6.2 +for details\&. This parameter cannot be set for TOAST tables\&. +.RE +.SH "NOTES" +.PP +PostgreSQL +automatically creates an index for each unique constraint and primary key constraint to enforce uniqueness\&. Thus, it is not necessary to create an index explicitly for primary key columns\&. (See +CREATE INDEX (\fBCREATE_INDEX\fR(7)) +for more information\&.) +.PP +Unique constraints and primary keys are not inherited in the current implementation\&. This makes the combination of inheritance and unique constraints rather dysfunctional\&. +.PP +A table cannot have more than 1600 columns\&. (In practice, the effective limit is usually lower because of tuple\-length constraints\&.) +.SH "EXAMPLES" +.PP +Create table +films +and table +distributors: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE films ( + code char(5) CONSTRAINT firstkey PRIMARY KEY, + title varchar(40) NOT NULL, + did integer NOT NULL, + date_prod date, + kind varchar(10), + len interval hour to minute +); + +CREATE TABLE distributors ( + did integer PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, + name varchar(40) NOT NULL CHECK (name <> \*(Aq\*(Aq) +); +.fi +.if n \{\ +.RE +.\} +.PP +Create a table with a 2\-dimensional array: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE array_int ( + vector int[][] +); +.fi +.if n \{\ +.RE +.\} +.PP +Define a unique table constraint for the table +films\&. Unique table constraints can be defined on one or more columns of the table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE films ( + code char(5), + title varchar(40), + did integer, + date_prod date, + kind varchar(10), + len interval hour to minute, + CONSTRAINT production UNIQUE(date_prod) +); +.fi +.if n \{\ +.RE +.\} +.PP +Define a check column constraint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer CHECK (did > 100), + name varchar(40) +); +.fi +.if n \{\ +.RE +.\} +.PP +Define a check table constraint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer, + name varchar(40), + CONSTRAINT con1 CHECK (did > 100 AND name <> \*(Aq\*(Aq) +); +.fi +.if n \{\ +.RE +.\} +.PP +Define a primary key table constraint for the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE films ( + code char(5), + title varchar(40), + did integer, + date_prod date, + kind varchar(10), + len interval hour to minute, + CONSTRAINT code_title PRIMARY KEY(code,title) +); +.fi +.if n \{\ +.RE +.\} +.PP +Define a primary key constraint for table +distributors\&. The following two examples are equivalent, the first using the table constraint syntax, the second the column constraint syntax: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer, + name varchar(40), + PRIMARY KEY(did) +); + +CREATE TABLE distributors ( + did integer PRIMARY KEY, + name varchar(40) +); +.fi +.if n \{\ +.RE +.\} +.PP +Assign a literal constant default value for the column +name, arrange for the default value of column +did +to be generated by selecting the next value of a sequence object, and make the default value of +modtime +be the time at which the row is inserted: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + name varchar(40) DEFAULT \*(AqLuso Films\*(Aq, + did integer DEFAULT nextval(\*(Aqdistributors_serial\*(Aq), + modtime timestamp DEFAULT current_timestamp +); +.fi +.if n \{\ +.RE +.\} +.PP +Define two +NOT NULL +column constraints on the table +distributors, one of which is explicitly given a name: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer CONSTRAINT no_null NOT NULL, + name varchar(40) NOT NULL +); +.fi +.if n \{\ +.RE +.\} +.PP +Define a unique constraint for the +name +column: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer, + name varchar(40) UNIQUE +); +.fi +.if n \{\ +.RE +.\} +.sp +The same, specified as a table constraint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer, + name varchar(40), + UNIQUE(name) +); +.fi +.if n \{\ +.RE +.\} +.PP +Create the same table, specifying 70% fill factor for both the table and its unique index: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE distributors ( + did integer, + name varchar(40), + UNIQUE(name) WITH (fillfactor=70) +) +WITH (fillfactor=70); +.fi +.if n \{\ +.RE +.\} +.PP +Create table +circles +with an exclusion constraint that prevents any two circles from overlapping: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE circles ( + c circle, + EXCLUDE USING gist (c WITH &&) +); +.fi +.if n \{\ +.RE +.\} +.PP +Create table +cinemas +in tablespace +diskvol1: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE cinemas ( + id serial, + name text, + location text +) TABLESPACE diskvol1; +.fi +.if n \{\ +.RE +.\} +.PP +Create a composite type and a typed table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE employee_type AS (name text, salary numeric); + +CREATE TABLE employees OF employee_type ( + PRIMARY KEY (name), + salary WITH OPTIONS DEFAULT 1000 +); +.fi +.if n \{\ +.RE +.\} +.PP +Create a range partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE measurement ( + logdate date not null, + peaktemp int, + unitsales int +) PARTITION BY RANGE (logdate); +.fi +.if n \{\ +.RE +.\} +.PP +Create a range partitioned table with multiple columns in the partition key: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE measurement_year_month ( + logdate date not null, + peaktemp int, + unitsales int +) PARTITION BY RANGE (EXTRACT(YEAR FROM logdate), EXTRACT(MONTH FROM logdate)); +.fi +.if n \{\ +.RE +.\} +.PP +Create a list partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE cities ( + city_id bigserial not null, + name text not null, + population bigint +) PARTITION BY LIST (left(lower(name), 1)); +.fi +.if n \{\ +.RE +.\} +.PP +Create a hash partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE orders ( + order_id bigint not null, + cust_id bigint not null, + status text +) PARTITION BY HASH (order_id); +.fi +.if n \{\ +.RE +.\} +.PP +Create partition of a range partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE measurement_y2016m07 + PARTITION OF measurement ( + unitsales DEFAULT 0 +) FOR VALUES FROM (\*(Aq2016\-07\-01\*(Aq) TO (\*(Aq2016\-08\-01\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Create a few partitions of a range partitioned table with multiple columns in the partition key: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE measurement_ym_older + PARTITION OF measurement_year_month + FOR VALUES FROM (MINVALUE, MINVALUE) TO (2016, 11); + +CREATE TABLE measurement_ym_y2016m11 + PARTITION OF measurement_year_month + FOR VALUES FROM (2016, 11) TO (2016, 12); + +CREATE TABLE measurement_ym_y2016m12 + PARTITION OF measurement_year_month + FOR VALUES FROM (2016, 12) TO (2017, 01); + +CREATE TABLE measurement_ym_y2017m01 + PARTITION OF measurement_year_month + FOR VALUES FROM (2017, 01) TO (2017, 02); +.fi +.if n \{\ +.RE +.\} +.PP +Create partition of a list partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE cities_ab + PARTITION OF cities ( + CONSTRAINT city_id_nonzero CHECK (city_id != 0) +) FOR VALUES IN (\*(Aqa\*(Aq, \*(Aqb\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Create partition of a list partitioned table that is itself further partitioned and then add a partition to it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE cities_ab + PARTITION OF cities ( + CONSTRAINT city_id_nonzero CHECK (city_id != 0) +) FOR VALUES IN (\*(Aqa\*(Aq, \*(Aqb\*(Aq) PARTITION BY RANGE (population); + +CREATE TABLE cities_ab_10000_to_100000 + PARTITION OF cities_ab FOR VALUES FROM (10000) TO (100000); +.fi +.if n \{\ +.RE +.\} +.PP +Create partitions of a hash partitioned table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE orders_p1 PARTITION OF orders + FOR VALUES WITH (MODULUS 4, REMAINDER 0); +CREATE TABLE orders_p2 PARTITION OF orders + FOR VALUES WITH (MODULUS 4, REMAINDER 1); +CREATE TABLE orders_p3 PARTITION OF orders + FOR VALUES WITH (MODULUS 4, REMAINDER 2); +CREATE TABLE orders_p4 PARTITION OF orders + FOR VALUES WITH (MODULUS 4, REMAINDER 3); +.fi +.if n \{\ +.RE +.\} +.PP +Create a default partition: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE cities_partdef + PARTITION OF cities DEFAULT; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBCREATE TABLE\fR +command conforms to the +SQL +standard, with exceptions listed below\&. +.SS "Temporary Tables" +.PP +Although the syntax of +CREATE TEMPORARY TABLE +resembles that of the SQL standard, the effect is not the same\&. In the standard, temporary tables are defined just once and automatically exist (starting with empty contents) in every session that needs them\&. +PostgreSQL +instead requires each session to issue its own +CREATE TEMPORARY TABLE +command for each temporary table to be used\&. This allows different sessions to use the same temporary table name for different purposes, whereas the standard\*(Aqs approach constrains all instances of a given temporary table name to have the same table structure\&. +.PP +The standard\*(Aqs definition of the behavior of temporary tables is widely ignored\&. +PostgreSQL\*(Aqs behavior on this point is similar to that of several other SQL databases\&. +.PP +The SQL standard also distinguishes between global and local temporary tables, where a local temporary table has a separate set of contents for each SQL module within each session, though its definition is still shared across sessions\&. Since +PostgreSQL +does not support SQL modules, this distinction is not relevant in +PostgreSQL\&. +.PP +For compatibility\*(Aqs sake, +PostgreSQL +will accept the +GLOBAL +and +LOCAL +keywords in a temporary table declaration, but they currently have no effect\&. Use of these keywords is discouraged, since future versions of +PostgreSQL +might adopt a more standard\-compliant interpretation of their meaning\&. +.PP +The +ON COMMIT +clause for temporary tables also resembles the SQL standard, but has some differences\&. If the +ON COMMIT +clause is omitted, SQL specifies that the default behavior is +ON COMMIT DELETE ROWS\&. However, the default behavior in +PostgreSQL +is +ON COMMIT PRESERVE ROWS\&. The +ON COMMIT DROP +option does not exist in SQL\&. +.SS "Non\-Deferred Uniqueness Constraints" +.PP +When a +UNIQUE +or +PRIMARY KEY +constraint is not deferrable, +PostgreSQL +checks for uniqueness immediately whenever a row is inserted or modified\&. The SQL standard says that uniqueness should be enforced only at the end of the statement; this makes a difference when, for example, a single command updates multiple key values\&. To obtain standard\-compliant behavior, declare the constraint as +DEFERRABLE +but not deferred (i\&.e\&., +INITIALLY IMMEDIATE)\&. Be aware that this can be significantly slower than immediate uniqueness checking\&. +.SS "Column Check Constraints" +.PP +The SQL standard says that +CHECK +column constraints can only refer to the column they apply to; only +CHECK +table constraints can refer to multiple columns\&. +PostgreSQL +does not enforce this restriction; it treats column and table check constraints alike\&. +.SS "EXCLUDE Constraint" +.PP +The +EXCLUDE +constraint type is a +PostgreSQL +extension\&. +.SS "Foreign\-Key Constraint Actions" +.PP +The ability to specify column lists in the foreign\-key actions +SET DEFAULT +and +SET NULL +is a +PostgreSQL +extension\&. +.SS "NULL \(lqConstraint\(rq" +.PP +The +NULL +\(lqconstraint\(rq +(actually a non\-constraint) is a +PostgreSQL +extension to the SQL standard that is included for compatibility with some other database systems (and for symmetry with the +NOT NULL +constraint)\&. Since it is the default for any column, its presence is simply noise\&. +.SS "Constraint Naming" +.PP +The SQL standard says that table and domain constraints must have names that are unique across the schema containing the table or domain\&. +PostgreSQL +is laxer: it only requires constraint names to be unique across the constraints attached to a particular table or domain\&. However, this extra freedom does not exist for index\-based constraints (UNIQUE, +PRIMARY KEY, and +EXCLUDE +constraints), because the associated index is named the same as the constraint, and index names must be unique across all relations within the same schema\&. +.PP +Currently, +PostgreSQL +does not record names for +NOT NULL +constraints at all, so they are not subject to the uniqueness restriction\&. This might change in a future release\&. +.SS "Inheritance" +.PP +Multiple inheritance via the +INHERITS +clause is a +PostgreSQL +language extension\&. SQL:1999 and later define single inheritance using a different syntax and different semantics\&. SQL:1999\-style inheritance is not yet supported by +PostgreSQL\&. +.SS "Zero\-Column Tables" +.PP +PostgreSQL +allows a table of no columns to be created (for example, +CREATE TABLE foo();)\&. This is an extension from the SQL standard, which does not allow zero\-column tables\&. Zero\-column tables are not in themselves very useful, but disallowing them creates odd special cases for +\fBALTER TABLE DROP COLUMN\fR, so it seems cleaner to ignore this spec restriction\&. +.SS "Multiple Identity Columns" +.PP +PostgreSQL +allows a table to have more than one identity column\&. The standard specifies that a table can have at most one identity column\&. This is relaxed mainly to give more flexibility for doing schema changes or migrations\&. Note that the +\fBINSERT\fR +command supports only one override clause that applies to the entire statement, so having multiple identity columns with different behaviors is not well supported\&. +.SS "Generated Columns" +.PP +The option +STORED +is not standard but is also used by other SQL implementations\&. The SQL standard does not specify the storage of generated columns\&. +.SS "LIKE Clause" +.PP +While a +LIKE +clause exists in the SQL standard, many of the options that +PostgreSQL +accepts for it are not in the standard, and some of the standard\*(Aqs options are not implemented by +PostgreSQL\&. +.SS "WITH Clause" +.PP +The +WITH +clause is a +PostgreSQL +extension; storage parameters are not in the standard\&. +.SS "Tablespaces" +.PP +The +PostgreSQL +concept of tablespaces is not part of the standard\&. Hence, the clauses +TABLESPACE +and +USING INDEX TABLESPACE +are extensions\&. +.SS "Typed Tables" +.PP +Typed tables implement a subset of the SQL standard\&. According to the standard, a typed table has columns corresponding to the underlying composite type as well as one other column that is the +\(lqself\-referencing column\(rq\&. +PostgreSQL +does not support self\-referencing columns explicitly\&. +.SS "PARTITION BY Clause" +.PP +The +PARTITION BY +clause is a +PostgreSQL +extension\&. +.SS "PARTITION OF Clause" +.PP +The +PARTITION OF +clause is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER TABLE (\fBALTER_TABLE\fR(7)), DROP TABLE (\fBDROP_TABLE\fR(7)), CREATE TABLE AS (\fBCREATE_TABLE_AS\fR(7)), CREATE TABLESPACE (\fBCREATE_TABLESPACE\fR(7)), CREATE TYPE (\fBCREATE_TYPE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TABLESPACE.7 b/doc/src/sgml/man7/CREATE_TABLESPACE.7 new file mode 100644 index 0000000..cc9b4c0 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TABLESPACE.7 @@ -0,0 +1,162 @@ +'\" t +.\" Title: CREATE TABLESPACE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TABLESPACE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TABLESPACE \- define a new tablespace +.SH "SYNOPSIS" +.sp +.nf +CREATE TABLESPACE \fItablespace_name\fR + [ OWNER { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ] + LOCATION \*(Aq\fIdirectory\fR\*(Aq + [ WITH ( \fItablespace_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TABLESPACE\fR +registers a new cluster\-wide tablespace\&. The tablespace name must be distinct from the name of any existing tablespace in the database cluster\&. +.PP +A tablespace allows superusers to define an alternative location on the file system where the data files containing database objects (such as tables and indexes) can reside\&. +.PP +A user with appropriate privileges can pass +\fItablespace_name\fR +to +\fBCREATE DATABASE\fR, +\fBCREATE TABLE\fR, +\fBCREATE INDEX\fR +or +\fBADD CONSTRAINT\fR +to have the data files for these objects stored within the specified tablespace\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +.PP +A tablespace cannot be used independently of the cluster in which it is defined; see +Section\ \&23.6\&. +.sp .5v +.RE +.SH "PARAMETERS" +.PP +\fItablespace_name\fR +.RS 4 +The name of a tablespace to be created\&. The name cannot begin with +pg_, as such names are reserved for system tablespaces\&. +.RE +.PP +\fIuser_name\fR +.RS 4 +The name of the user who will own the tablespace\&. If omitted, defaults to the user executing the command\&. Only superusers can create tablespaces, but they can assign ownership of tablespaces to non\-superusers\&. +.RE +.PP +\fIdirectory\fR +.RS 4 +The directory that will be used for the tablespace\&. The directory must exist (\fBCREATE TABLESPACE\fR +will not create it), should be empty, and must be owned by the +PostgreSQL +system user\&. The directory must be specified by an absolute path name\&. +.RE +.PP +\fItablespace_option\fR +.RS 4 +A tablespace parameter to be set or reset\&. Currently, the only available parameters are +\fIseq_page_cost\fR, +\fIrandom_page_cost\fR, +\fIeffective_io_concurrency\fR +and +\fImaintenance_io_concurrency\fR\&. Setting these values for a particular tablespace will override the planner\*(Aqs usual estimate of the cost of reading pages from tables in that tablespace, and the executor\*(Aqs prefetching behavior, as established by the configuration parameters of the same name (see +seq_page_cost, +random_page_cost, +effective_io_concurrency, +maintenance_io_concurrency)\&. This may be useful if one tablespace is located on a disk which is faster or slower than the remainder of the I/O subsystem\&. +.RE +.SH "NOTES" +.PP +Tablespaces are only supported on systems that support symbolic links\&. +.PP +\fBCREATE TABLESPACE\fR +cannot be executed inside a transaction block\&. +.SH "EXAMPLES" +.PP +To create a tablespace +dbspace +at file system location +/data/dbs, first create the directory using operating system facilities and set the correct ownership: +.sp +.if n \{\ +.RS 4 +.\} +.nf +mkdir /data/dbs +chown postgres:postgres /data/dbs +.fi +.if n \{\ +.RE +.\} +.sp +Then issue the tablespace creation command inside +PostgreSQL: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLESPACE dbspace LOCATION \*(Aq/data/dbs\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To create a tablespace owned by a different database user, use a command like this: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLESPACE indexspace OWNER genevieve LOCATION \*(Aq/data/indexes\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE TABLESPACE\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE DATABASE (\fBCREATE_DATABASE\fR(7)), CREATE TABLE (\fBCREATE_TABLE\fR(7)), CREATE INDEX (\fBCREATE_INDEX\fR(7)), DROP TABLESPACE (\fBDROP_TABLESPACE\fR(7)), ALTER TABLESPACE (\fBALTER_TABLESPACE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TABLE_AS.7 b/doc/src/sgml/man7/CREATE_TABLE_AS.7 new file mode 100644 index 0000000..f808702 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TABLE_AS.7 @@ -0,0 +1,320 @@ +'\" t +.\" Title: CREATE TABLE AS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TABLE AS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TABLE_AS \- define a new table from the results of a query +.SH "SYNOPSIS" +.sp +.nf +CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXISTS ] \fItable_name\fR + [ (\fIcolumn_name\fR [, \&.\&.\&.] ) ] + [ USING \fImethod\fR ] + [ WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) | WITHOUT OIDS ] + [ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ] + [ TABLESPACE \fItablespace_name\fR ] + AS \fIquery\fR + [ WITH [ NO ] DATA ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TABLE AS\fR +creates a table and fills it with data computed by a +\fBSELECT\fR +command\&. The table columns have the names and data types associated with the output columns of the +\fBSELECT\fR +(except that you can override the column names by giving an explicit list of new column names)\&. +.PP +\fBCREATE TABLE AS\fR +bears some resemblance to creating a view, but it is really quite different: it creates a new table and evaluates the query just once to fill the new table initially\&. The new table will not track subsequent changes to the source tables of the query\&. In contrast, a view re\-evaluates its defining +\fBSELECT\fR +statement whenever it is queried\&. +.PP +\fBCREATE TABLE AS\fR +requires +CREATE +privilege on the schema used for the table\&. +.SH "PARAMETERS" +.PP +GLOBAL or LOCAL +.RS 4 +Ignored for compatibility\&. Use of these keywords is deprecated; refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for details\&. +.RE +.PP +TEMPORARY or TEMP +.RS 4 +If specified, the table is created as a temporary table\&. Refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for details\&. +.RE +.PP +UNLOGGED +.RS 4 +If specified, the table is created as an unlogged table\&. Refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for details\&. +.RE +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a relation with the same name already exists; simply issue a notice and leave the table unmodified\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table to be created\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column in the new table\&. If column names are not provided, they are taken from the output column names of the query\&. +.RE +.PP +USING \fImethod\fR +.RS 4 +This optional clause specifies the table access method to use to store the contents for the new table; the method needs be an access method of type +TABLE\&. See +Chapter\ \&63 +for more information\&. If this option is not specified, the default table access method is chosen for the new table\&. See +default_table_access_method +for more information\&. +.RE +.PP +WITH ( \fIstorage_parameter\fR [= \fIvalue\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause specifies optional storage parameters for the new table; see +Storage Parameters +in the +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +documentation for more information\&. For backward\-compatibility the +WITH +clause for a table can also include +OIDS=FALSE +to specify that rows of the new table should contain no OIDs (object identifiers), +OIDS=TRUE +is not supported anymore\&. +.RE +.PP +WITHOUT OIDS +.RS 4 +This is backward\-compatible syntax for declaring a table +WITHOUT OIDS, creating a table +WITH OIDS +is not supported anymore\&. +.RE +.PP +ON COMMIT +.RS 4 +The behavior of temporary tables at the end of a transaction block can be controlled using +ON COMMIT\&. The three options are: +.PP +PRESERVE ROWS +.RS 4 +No special action is taken at the ends of transactions\&. This is the default behavior\&. +.RE +.PP +DELETE ROWS +.RS 4 +All rows in the temporary table will be deleted at the end of each transaction block\&. Essentially, an automatic +\fBTRUNCATE\fR +is done at each commit\&. +.RE +.PP +DROP +.RS 4 +The temporary table will be dropped at the end of the current transaction block\&. +.RE +.RE +.PP +TABLESPACE \fItablespace_name\fR +.RS 4 +The +\fItablespace_name\fR +is the name of the tablespace in which the new table is to be created\&. If not specified, +default_tablespace +is consulted, or +temp_tablespaces +if the table is temporary\&. +.RE +.PP +\fIquery\fR +.RS 4 +A +\fBSELECT\fR, +\fBTABLE\fR, or +\fBVALUES\fR +command, or an +\fBEXECUTE\fR +command that runs a prepared +\fBSELECT\fR, +\fBTABLE\fR, or +\fBVALUES\fR +query\&. +.RE +.PP +WITH [ NO ] DATA +.RS 4 +This clause specifies whether or not the data produced by the query should be copied into the new table\&. If not, only the table structure is copied\&. The default is to copy the data\&. +.RE +.SH "NOTES" +.PP +This command is functionally similar to +SELECT INTO (\fBSELECT_INTO\fR(7)), but it is preferred since it is less likely to be confused with other uses of the +\fBSELECT INTO\fR +syntax\&. Furthermore, +\fBCREATE TABLE AS\fR +offers a superset of the functionality offered by +\fBSELECT INTO\fR\&. +.SH "EXAMPLES" +.PP +Create a new table +films_recent +consisting of only recent entries from the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE films_recent AS + SELECT * FROM films WHERE date_prod >= \*(Aq2002\-01\-01\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +To copy a table completely, the short form using the +TABLE +command can also be used: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TABLE films2 AS + TABLE films; +.fi +.if n \{\ +.RE +.\} +.PP +Create a new temporary table +films_recent, consisting of only recent entries from the table +films, using a prepared statement\&. The new table will be dropped at commit: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PREPARE recentfilms(date) AS + SELECT * FROM films WHERE date_prod > $1; +CREATE TEMP TABLE films_recent ON COMMIT DROP AS + EXECUTE recentfilms(\*(Aq2002\-01\-01\*(Aq); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE TABLE AS\fR +conforms to the +SQL +standard\&. The following are nonstandard extensions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The standard requires parentheses around the subquery clause; in +PostgreSQL, these parentheses are optional\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +In the standard, the +WITH [ NO ] DATA +clause is required; in PostgreSQL it is optional\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +PostgreSQL +handles temporary tables in a way rather different from the standard; see +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for details\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +WITH +clause is a +PostgreSQL +extension; storage parameters are not in the standard\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +PostgreSQL +concept of tablespaces is not part of the standard\&. Hence, the clause +TABLESPACE +is an extension\&. +.RE +.SH "SEE ALSO" +CREATE MATERIALIZED VIEW (\fBCREATE_MATERIALIZED_VIEW\fR(7)), CREATE TABLE (\fBCREATE_TABLE\fR(7)), \fBEXECUTE\fR(7), \fBSELECT\fR(7), SELECT INTO (\fBSELECT_INTO\fR(7)), \fBVALUES\fR(7) diff --git a/doc/src/sgml/man7/CREATE_TEXT_SEARCH_CONFIGURATION.7 b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_CONFIGURATION.7 new file mode 100644 index 0000000..78acd16 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_CONFIGURATION.7 @@ -0,0 +1,85 @@ +'\" t +.\" Title: CREATE TEXT SEARCH CONFIGURATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TEXT SEARCH CONFIGURATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TEXT_SEARCH_CONFIGURATION \- define a new text search configuration +.SH "SYNOPSIS" +.sp +.nf +CREATE TEXT SEARCH CONFIGURATION \fIname\fR ( + PARSER = \fIparser_name\fR | + COPY = \fIsource_config\fR +) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TEXT SEARCH CONFIGURATION\fR +creates a new text search configuration\&. A text search configuration specifies a text search parser that can divide a string into tokens, plus dictionaries that can be used to determine which tokens are of interest for searching\&. +.PP +If only the parser is specified, then the new text search configuration initially has no mappings from token types to dictionaries, and therefore will ignore all words\&. Subsequent +\fBALTER TEXT SEARCH CONFIGURATION\fR +commands must be used to create mappings to make the configuration useful\&. Alternatively, an existing text search configuration can be copied\&. +.PP +If a schema name is given then the text search configuration is created in the specified schema\&. Otherwise it is created in the current schema\&. +.PP +The user who defines a text search configuration becomes its owner\&. +.PP +Refer to +Chapter\ \&12 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the text search configuration to be created\&. The name can be schema\-qualified\&. +.RE +.PP +\fIparser_name\fR +.RS 4 +The name of the text search parser to use for this configuration\&. +.RE +.PP +\fIsource_config\fR +.RS 4 +The name of an existing text search configuration to copy\&. +.RE +.SH "NOTES" +.PP +The +PARSER +and +COPY +options are mutually exclusive, because when an existing configuration is copied, its parser selection is copied too\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE TEXT SEARCH CONFIGURATION\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH CONFIGURATION (\fBALTER_TEXT_SEARCH_CONFIGURATION\fR(7)), DROP TEXT SEARCH CONFIGURATION (\fBDROP_TEXT_SEARCH_CONFIGURATION\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TEXT_SEARCH_DICTIONARY.7 b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_DICTIONARY.7 new file mode 100644 index 0000000..dc46c35 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_DICTIONARY.7 @@ -0,0 +1,98 @@ +'\" t +.\" Title: CREATE TEXT SEARCH DICTIONARY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TEXT SEARCH DICTIONARY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TEXT_SEARCH_DICTIONARY \- define a new text search dictionary +.SH "SYNOPSIS" +.sp +.nf +CREATE TEXT SEARCH DICTIONARY \fIname\fR ( + TEMPLATE = \fItemplate\fR + [, \fIoption\fR = \fIvalue\fR [, \&.\&.\&. ]] +) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TEXT SEARCH DICTIONARY\fR +creates a new text search dictionary\&. A text search dictionary specifies a way of recognizing interesting or uninteresting words for searching\&. A dictionary depends on a text search template, which specifies the functions that actually perform the work\&. Typically the dictionary provides some options that control the detailed behavior of the template\*(Aqs functions\&. +.PP +If a schema name is given then the text search dictionary is created in the specified schema\&. Otherwise it is created in the current schema\&. +.PP +The user who defines a text search dictionary becomes its owner\&. +.PP +Refer to +Chapter\ \&12 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the text search dictionary to be created\&. The name can be schema\-qualified\&. +.RE +.PP +\fItemplate\fR +.RS 4 +The name of the text search template that will define the basic behavior of this dictionary\&. +.RE +.PP +\fIoption\fR +.RS 4 +The name of a template\-specific option to be set for this dictionary\&. +.RE +.PP +\fIvalue\fR +.RS 4 +The value to use for a template\-specific option\&. If the value is not a simple identifier or number, it must be quoted (but you can always quote it, if you wish)\&. +.RE +.PP +The options can appear in any order\&. +.SH "EXAMPLES" +.PP +The following example command creates a Snowball\-based dictionary with a nonstandard list of stop words\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TEXT SEARCH DICTIONARY my_russian ( + template = snowball, + language = russian, + stopwords = myrussian +); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE TEXT SEARCH DICTIONARY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH DICTIONARY (\fBALTER_TEXT_SEARCH_DICTIONARY\fR(7)), DROP TEXT SEARCH DICTIONARY (\fBDROP_TEXT_SEARCH_DICTIONARY\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TEXT_SEARCH_PARSER.7 b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_PARSER.7 new file mode 100644 index 0000000..e0c003c --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_PARSER.7 @@ -0,0 +1,97 @@ +'\" t +.\" Title: CREATE TEXT SEARCH PARSER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TEXT SEARCH PARSER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TEXT_SEARCH_PARSER \- define a new text search parser +.SH "SYNOPSIS" +.sp +.nf +CREATE TEXT SEARCH PARSER \fIname\fR ( + START = \fIstart_function\fR , + GETTOKEN = \fIgettoken_function\fR , + END = \fIend_function\fR , + LEXTYPES = \fIlextypes_function\fR + [, HEADLINE = \fIheadline_function\fR ] +) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TEXT SEARCH PARSER\fR +creates a new text search parser\&. A text search parser defines a method for splitting a text string into tokens and assigning types (categories) to the tokens\&. A parser is not particularly useful by itself, but must be bound into a text search configuration along with some text search dictionaries to be used for searching\&. +.PP +If a schema name is given then the text search parser is created in the specified schema\&. Otherwise it is created in the current schema\&. +.PP +You must be a superuser to use +\fBCREATE TEXT SEARCH PARSER\fR\&. (This restriction is made because an erroneous text search parser definition could confuse or even crash the server\&.) +.PP +Refer to +Chapter\ \&12 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the text search parser to be created\&. The name can be schema\-qualified\&. +.RE +.PP +\fIstart_function\fR +.RS 4 +The name of the start function for the parser\&. +.RE +.PP +\fIgettoken_function\fR +.RS 4 +The name of the get\-next\-token function for the parser\&. +.RE +.PP +\fIend_function\fR +.RS 4 +The name of the end function for the parser\&. +.RE +.PP +\fIlextypes_function\fR +.RS 4 +The name of the lextypes function for the parser (a function that returns information about the set of token types it produces)\&. +.RE +.PP +\fIheadline_function\fR +.RS 4 +The name of the headline function for the parser (a function that summarizes a set of tokens)\&. +.RE +.PP +The function names can be schema\-qualified if necessary\&. Argument types are not given, since the argument list for each type of function is predetermined\&. All except the headline function are required\&. +.PP +The arguments can appear in any order, not only the one shown above\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE TEXT SEARCH PARSER\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH PARSER (\fBALTER_TEXT_SEARCH_PARSER\fR(7)), DROP TEXT SEARCH PARSER (\fBDROP_TEXT_SEARCH_PARSER\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TEXT_SEARCH_TEMPLATE.7 b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_TEMPLATE.7 new file mode 100644 index 0000000..7ae21ac --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TEXT_SEARCH_TEMPLATE.7 @@ -0,0 +1,81 @@ +'\" t +.\" Title: CREATE TEXT SEARCH TEMPLATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TEXT SEARCH TEMPLATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TEXT_SEARCH_TEMPLATE \- define a new text search template +.SH "SYNOPSIS" +.sp +.nf +CREATE TEXT SEARCH TEMPLATE \fIname\fR ( + [ INIT = \fIinit_function\fR , ] + LEXIZE = \fIlexize_function\fR +) +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TEXT SEARCH TEMPLATE\fR +creates a new text search template\&. Text search templates define the functions that implement text search dictionaries\&. A template is not useful by itself, but must be instantiated as a dictionary to be used\&. The dictionary typically specifies parameters to be given to the template functions\&. +.PP +If a schema name is given then the text search template is created in the specified schema\&. Otherwise it is created in the current schema\&. +.PP +You must be a superuser to use +\fBCREATE TEXT SEARCH TEMPLATE\fR\&. This restriction is made because an erroneous text search template definition could confuse or even crash the server\&. The reason for separating templates from dictionaries is that a template encapsulates the +\(lqunsafe\(rq +aspects of defining a dictionary\&. The parameters that can be set when defining a dictionary are safe for unprivileged users to set, and so creating a dictionary need not be a privileged operation\&. +.PP +Refer to +Chapter\ \&12 +for further information\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the text search template to be created\&. The name can be schema\-qualified\&. +.RE +.PP +\fIinit_function\fR +.RS 4 +The name of the init function for the template\&. +.RE +.PP +\fIlexize_function\fR +.RS 4 +The name of the lexize function for the template\&. +.RE +.PP +The function names can be schema\-qualified if necessary\&. Argument types are not given, since the argument list for each type of function is predetermined\&. The lexize function is required, but the init function is optional\&. +.PP +The arguments can appear in any order, not only the one shown above\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBCREATE TEXT SEARCH TEMPLATE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH TEMPLATE (\fBALTER_TEXT_SEARCH_TEMPLATE\fR(7)), DROP TEXT SEARCH TEMPLATE (\fBDROP_TEXT_SEARCH_TEMPLATE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TRANSFORM.7 b/doc/src/sgml/man7/CREATE_TRANSFORM.7 new file mode 100644 index 0000000..6358065 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TRANSFORM.7 @@ -0,0 +1,198 @@ +'\" t +.\" Title: CREATE TRANSFORM +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TRANSFORM" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TRANSFORM \- define a new transform +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] TRANSFORM FOR \fItype_name\fR LANGUAGE \fIlang_name\fR ( + FROM SQL WITH FUNCTION \fIfrom_sql_function_name\fR [ (\fIargument_type\fR [, \&.\&.\&.]) ], + TO SQL WITH FUNCTION \fIto_sql_function_name\fR [ (\fIargument_type\fR [, \&.\&.\&.]) ] +); +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TRANSFORM\fR +defines a new transform\&. +\fBCREATE OR REPLACE TRANSFORM\fR +will either create a new transform, or replace an existing definition\&. +.PP +A transform specifies how to adapt a data type to a procedural language\&. For example, when writing a function in PL/Python using the +hstore +type, PL/Python has no prior knowledge how to present +hstore +values in the Python environment\&. Language implementations usually default to using the text representation, but that is inconvenient when, for example, an associative array or a list would be more appropriate\&. +.PP +A transform specifies two functions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A +\(lqfrom SQL\(rq +function that converts the type from the SQL environment to the language\&. This function will be invoked on the arguments of a function written in the language\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +A +\(lqto SQL\(rq +function that converts the type from the language to the SQL environment\&. This function will be invoked on the return value of a function written in the language\&. +.RE +.sp +It is not necessary to provide both of these functions\&. If one is not specified, the language\-specific default behavior will be used if necessary\&. (To prevent a transformation in a certain direction from happening at all, you could also write a transform function that always errors out\&.) +.PP +To be able to create a transform, you must own and have +USAGE +privilege on the type, have +USAGE +privilege on the language, and own and have +EXECUTE +privilege on the from\-SQL and to\-SQL functions, if specified\&. +.SH "PARAMETERS" +.PP +\fItype_name\fR +.RS 4 +The name of the data type of the transform\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the language of the transform\&. +.RE +.PP +\fIfrom_sql_function_name\fR[(\fIargument_type\fR [, \&.\&.\&.])] +.RS 4 +The name of the function for converting the type from the SQL environment to the language\&. It must take one argument of type +internal +and return type +internal\&. The actual argument will be of the type for the transform, and the function should be coded as if it were\&. (But it is not allowed to declare an SQL\-level function returning +internal +without at least one argument of type +internal\&.) The actual return value will be something specific to the language implementation\&. If no argument list is specified, the function name must be unique in its schema\&. +.RE +.PP +\fIto_sql_function_name\fR[(\fIargument_type\fR [, \&.\&.\&.])] +.RS 4 +The name of the function for converting the type from the language to the SQL environment\&. It must take one argument of type +internal +and return the type that is the type for the transform\&. The actual argument value will be something specific to the language implementation\&. If no argument list is specified, the function name must be unique in its schema\&. +.RE +.SH "NOTES" +.PP +Use +\fBDROP TRANSFORM\fR +to remove transforms\&. +.SH "EXAMPLES" +.PP +To create a transform for type +hstore +and language +plpython3u, first set up the type and the language: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE hstore \&.\&.\&.; + +CREATE EXTENSION plpython3u; +.fi +.if n \{\ +.RE +.\} +.sp +Then create the necessary functions: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal +LANGUAGE C STRICT IMMUTABLE +AS \&.\&.\&.; + +CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore +LANGUAGE C STRICT IMMUTABLE +AS \&.\&.\&.; +.fi +.if n \{\ +.RE +.\} +.sp +And finally create the transform to connect them all together: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRANSFORM FOR hstore LANGUAGE plpython3u ( + FROM SQL WITH FUNCTION hstore_to_plpython(internal), + TO SQL WITH FUNCTION plpython_to_hstore(internal) +); +.fi +.if n \{\ +.RE +.\} +.sp +In practice, these commands would be wrapped up in an extension\&. +.PP +The +contrib +section contains a number of extensions that provide transforms, which can serve as real\-world examples\&. +.SH "COMPATIBILITY" +.PP +This form of +\fBCREATE TRANSFORM\fR +is a +PostgreSQL +extension\&. There is a +\fBCREATE TRANSFORM\fR +command in the +SQL +standard, but it is for adapting data types to client languages\&. That usage is not supported by +PostgreSQL\&. +.SH "SEE ALSO" +.PP +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), +CREATE LANGUAGE (\fBCREATE_LANGUAGE\fR(7)), +CREATE TYPE (\fBCREATE_TYPE\fR(7)), +DROP TRANSFORM (\fBDROP_TRANSFORM\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TRIGGER.7 b/doc/src/sgml/man7/CREATE_TRIGGER.7 new file mode 100644 index 0000000..6328eab --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TRIGGER.7 @@ -0,0 +1,715 @@ +'\" t +.\" Title: CREATE TRIGGER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TRIGGER \- define a new trigger +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] [ CONSTRAINT ] TRIGGER \fIname\fR { BEFORE | AFTER | INSTEAD OF } { \fIevent\fR [ OR \&.\&.\&. ] } + ON \fItable_name\fR + [ FROM \fIreferenced_table_name\fR ] + [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ] + [ REFERENCING { { OLD | NEW } TABLE [ AS ] \fItransition_relation_name\fR } [ \&.\&.\&. ] ] + [ FOR [ EACH ] { ROW | STATEMENT } ] + [ WHEN ( \fIcondition\fR ) ] + EXECUTE { FUNCTION | PROCEDURE } \fIfunction_name\fR ( \fIarguments\fR ) + +where \fIevent\fR can be one of: + + INSERT + UPDATE [ OF \fIcolumn_name\fR [, \&.\&.\&. ] ] + DELETE + TRUNCATE +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TRIGGER\fR +creates a new trigger\&. +\fBCREATE OR REPLACE TRIGGER\fR +will either create a new trigger, or replace an existing trigger\&. The trigger will be associated with the specified table, view, or foreign table and will execute the specified function +\fIfunction_name\fR +when certain operations are performed on that table\&. +.PP +To replace the current definition of an existing trigger, use +\fBCREATE OR REPLACE TRIGGER\fR, specifying the existing trigger\*(Aqs name and parent table\&. All other properties are replaced\&. +.PP +The trigger can be specified to fire before the operation is attempted on a row (before constraints are checked and the +\fBINSERT\fR, +\fBUPDATE\fR, or +\fBDELETE\fR +is attempted); or after the operation has completed (after constraints are checked and the +\fBINSERT\fR, +\fBUPDATE\fR, or +\fBDELETE\fR +has completed); or instead of the operation (in the case of inserts, updates or deletes on a view)\&. If the trigger fires before or instead of the event, the trigger can skip the operation for the current row, or change the row being inserted (for +\fBINSERT\fR +and +\fBUPDATE\fR +operations only)\&. If the trigger fires after the event, all changes, including the effects of other triggers, are +\(lqvisible\(rq +to the trigger\&. +.PP +A trigger that is marked +FOR EACH ROW +is called once for every row that the operation modifies\&. For example, a +\fBDELETE\fR +that affects 10 rows will cause any +ON DELETE +triggers on the target relation to be called 10 separate times, once for each deleted row\&. In contrast, a trigger that is marked +FOR EACH STATEMENT +only executes once for any given operation, regardless of how many rows it modifies (in particular, an operation that modifies zero rows will still result in the execution of any applicable +FOR EACH STATEMENT +triggers)\&. +.PP +Triggers that are specified to fire +INSTEAD OF +the trigger event must be marked +FOR EACH ROW, and can only be defined on views\&. +BEFORE +and +AFTER +triggers on a view must be marked as +FOR EACH STATEMENT\&. +.PP +In addition, triggers may be defined to fire for +\fBTRUNCATE\fR, though only +FOR EACH STATEMENT\&. +.PP +The following table summarizes which types of triggers may be used on tables, views, and foreign tables: +.TS +allbox tab(:); +lB lB lB lB. +T{ +When +T}:T{ +Event +T}:T{ +Row\-level +T}:T{ +Statement\-level +T} +.T& +c c c c +^ c c c +c c c c +^ c c c +c c c c +^ c c c. +T{ +BEFORE +T}:T{ +\fBINSERT\fR/\fBUPDATE\fR/\fBDELETE\fR +T}:T{ +Tables and foreign tables +T}:T{ +Tables, views, and foreign tables +T} +:T{ +\fBTRUNCATE\fR +T}:T{ +\(em +T}:T{ +Tables +T} +T{ +AFTER +T}:T{ +\fBINSERT\fR/\fBUPDATE\fR/\fBDELETE\fR +T}:T{ +Tables and foreign tables +T}:T{ +Tables, views, and foreign tables +T} +:T{ +\fBTRUNCATE\fR +T}:T{ +\(em +T}:T{ +Tables +T} +T{ +INSTEAD OF +T}:T{ +\fBINSERT\fR/\fBUPDATE\fR/\fBDELETE\fR +T}:T{ +Views +T}:T{ +\(em +T} +:T{ +\fBTRUNCATE\fR +T}:T{ +\(em +T}:T{ +\(em +T} +.TE +.sp 1 +.PP +Also, a trigger definition can specify a Boolean +WHEN +condition, which will be tested to see whether the trigger should be fired\&. In row\-level triggers the +WHEN +condition can examine the old and/or new values of columns of the row\&. Statement\-level triggers can also have +WHEN +conditions, although the feature is not so useful for them since the condition cannot refer to any values in the table\&. +.PP +If multiple triggers of the same kind are defined for the same event, they will be fired in alphabetical order by name\&. +.PP +When the +CONSTRAINT +option is specified, this command creates a +constraint trigger\&. +This is the same as a regular trigger except that the timing of the trigger firing can be adjusted using +\fBSET CONSTRAINTS\fR\&. Constraint triggers must be +AFTER ROW +triggers on plain tables (not foreign tables)\&. They can be fired either at the end of the statement causing the triggering event, or at the end of the containing transaction; in the latter case they are said to be +deferred\&. A pending deferred\-trigger firing can also be forced to happen immediately by using +\fBSET CONSTRAINTS\fR\&. Constraint triggers are expected to raise an exception when the constraints they implement are violated\&. +.PP +The +REFERENCING +option enables collection of +transition relations, which are row sets that include all of the rows inserted, deleted, or modified by the current SQL statement\&. This feature lets the trigger see a global view of what the statement did, not just one row at a time\&. This option is only allowed for an +AFTER +trigger that is not a constraint trigger; also, if the trigger is an +UPDATE +trigger, it must not specify a +\fIcolumn_name\fR +list\&. +OLD TABLE +may only be specified once, and only for a trigger that can fire on +UPDATE +or +DELETE; it creates a transition relation containing the +before\-images +of all rows updated or deleted by the statement\&. Similarly, +NEW TABLE +may only be specified once, and only for a trigger that can fire on +UPDATE +or +INSERT; it creates a transition relation containing the +after\-images +of all rows updated or inserted by the statement\&. +.PP +\fBSELECT\fR +does not modify any rows so you cannot create +\fBSELECT\fR +triggers\&. Rules and views may provide workable solutions to problems that seem to need +\fBSELECT\fR +triggers\&. +.PP +Refer to +Chapter\ \&39 +for more information about triggers\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name to give the new trigger\&. This must be distinct from the name of any other trigger for the same table\&. The name cannot be schema\-qualified \(em the trigger inherits the schema of its table\&. For a constraint trigger, this is also the name to use when modifying the trigger\*(Aqs behavior using +\fBSET CONSTRAINTS\fR\&. +.RE +.PP +BEFORE +.br +AFTER +.br +INSTEAD OF +.RS 4 +Determines whether the function is called before, after, or instead of the event\&. A constraint trigger can only be specified as +AFTER\&. +.RE +.PP +\fIevent\fR +.RS 4 +One of +INSERT, +UPDATE, +DELETE, or +TRUNCATE; this specifies the event that will fire the trigger\&. Multiple events can be specified using +OR, except when transition relations are requested\&. +.sp +For +UPDATE +events, it is possible to specify a list of columns using this syntax: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE OF \fIcolumn_name1\fR [, \fIcolumn_name2\fR \&.\&.\&. ] +.fi +.if n \{\ +.RE +.\} +.sp +The trigger will only fire if at least one of the listed columns is mentioned as a target of the +\fBUPDATE\fR +command or if one of the listed columns is a generated column that depends on a column that is the target of the +\fBUPDATE\fR\&. +.sp +INSTEAD OF UPDATE +events do not allow a list of columns\&. A column list cannot be specified when requesting transition relations, either\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table, view, or foreign table the trigger is for\&. +.RE +.PP +\fIreferenced_table_name\fR +.RS 4 +The (possibly schema\-qualified) name of another table referenced by the constraint\&. This option is used for foreign\-key constraints and is not recommended for general use\&. This can only be specified for constraint triggers\&. +.RE +.PP +DEFERRABLE +.br +NOT DEFERRABLE +.br +INITIALLY IMMEDIATE +.br +INITIALLY DEFERRED +.RS 4 +The default timing of the trigger\&. See the +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +documentation for details of these constraint options\&. This can only be specified for constraint triggers\&. +.RE +.PP +REFERENCING +.RS 4 +This keyword immediately precedes the declaration of one or two relation names that provide access to the transition relations of the triggering statement\&. +.RE +.PP +OLD TABLE +.br +NEW TABLE +.RS 4 +This clause indicates whether the following relation name is for the before\-image transition relation or the after\-image transition relation\&. +.RE +.PP +\fItransition_relation_name\fR +.RS 4 +The (unqualified) name to be used within the trigger for this transition relation\&. +.RE +.PP +FOR EACH ROW +.br +FOR EACH STATEMENT +.RS 4 +This specifies whether the trigger function should be fired once for every row affected by the trigger event, or just once per SQL statement\&. If neither is specified, +FOR EACH STATEMENT +is the default\&. Constraint triggers can only be specified +FOR EACH ROW\&. +.RE +.PP +\fIcondition\fR +.RS 4 +A Boolean expression that determines whether the trigger function will actually be executed\&. If +WHEN +is specified, the function will only be called if the +\fIcondition\fR +returns +true\&. In +FOR EACH ROW +triggers, the +WHEN +condition can refer to columns of the old and/or new row values by writing +OLD\&.\fIcolumn_name\fR +or +NEW\&.\fIcolumn_name\fR +respectively\&. Of course, +INSERT +triggers cannot refer to +OLD +and +DELETE +triggers cannot refer to +NEW\&. +.sp +INSTEAD OF +triggers do not support +WHEN +conditions\&. +.sp +Currently, +WHEN +expressions cannot contain subqueries\&. +.sp +Note that for constraint triggers, evaluation of the +WHEN +condition is not deferred, but occurs immediately after the row update operation is performed\&. If the condition does not evaluate to true then the trigger is not queued for deferred execution\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +A user\-supplied function that is declared as taking no arguments and returning type +trigger, which is executed when the trigger fires\&. +.sp +In the syntax of +CREATE TRIGGER, the keywords +FUNCTION +and +PROCEDURE +are equivalent, but the referenced function must in any case be a function, not a procedure\&. The use of the keyword +PROCEDURE +here is historical and deprecated\&. +.RE +.PP +\fIarguments\fR +.RS 4 +An optional comma\-separated list of arguments to be provided to the function when the trigger is executed\&. The arguments are literal string constants\&. Simple names and numeric constants can be written here, too, but they will all be converted to strings\&. Please check the description of the implementation language of the trigger function to find out how these arguments can be accessed within the function; it might be different from normal function arguments\&. +.RE +.SH "NOTES" +.PP +To create or replace a trigger on a table, the user must have the +TRIGGER +privilege on the table\&. The user must also have +EXECUTE +privilege on the trigger function\&. +.PP +Use +\fBDROP TRIGGER\fR +to remove a trigger\&. +.PP +Creating a row\-level trigger on a partitioned table will cause an identical +\(lqclone\(rq +trigger to be created on each of its existing partitions; and any partitions created or attached later will have an identical trigger, too\&. If there is a conflictingly\-named trigger on a child partition already, an error occurs unless +\fBCREATE OR REPLACE TRIGGER\fR +is used, in which case that trigger is replaced with a clone trigger\&. When a partition is detached from its parent, its clone triggers are removed\&. +.PP +A column\-specific trigger (one defined using the +UPDATE OF \fIcolumn_name\fR +syntax) will fire when any of its columns are listed as targets in the +\fBUPDATE\fR +command\*(Aqs +SET +list\&. It is possible for a column\*(Aqs value to change even when the trigger is not fired, because changes made to the row\*(Aqs contents by +BEFORE UPDATE +triggers are not considered\&. Conversely, a command such as +UPDATE \&.\&.\&. SET x = x \&.\&.\&. +will fire a trigger on column +x, even though the column\*(Aqs value did not change\&. +.PP +In a +BEFORE +trigger, the +WHEN +condition is evaluated just before the function is or would be executed, so using +WHEN +is not materially different from testing the same condition at the beginning of the trigger function\&. Note in particular that the +NEW +row seen by the condition is the current value, as possibly modified by earlier triggers\&. Also, a +BEFORE +trigger\*(Aqs +WHEN +condition is not allowed to examine the system columns of the +NEW +row (such as +ctid), because those won\*(Aqt have been set yet\&. +.PP +In an +AFTER +trigger, the +WHEN +condition is evaluated just after the row update occurs, and it determines whether an event is queued to fire the trigger at the end of statement\&. So when an +AFTER +trigger\*(Aqs +WHEN +condition does not return true, it is not necessary to queue an event nor to re\-fetch the row at end of statement\&. This can result in significant speedups in statements that modify many rows, if the trigger only needs to be fired for a few of the rows\&. +.PP +In some cases it is possible for a single SQL command to fire more than one kind of trigger\&. For instance an +\fBINSERT\fR +with an +ON CONFLICT DO UPDATE +clause may cause both insert and update operations, so it will fire both kinds of triggers as needed\&. The transition relations supplied to triggers are specific to their event type; thus an +\fBINSERT\fR +trigger will see only the inserted rows, while an +\fBUPDATE\fR +trigger will see only the updated rows\&. +.PP +Row updates or deletions caused by foreign\-key enforcement actions, such as +ON UPDATE CASCADE +or +ON DELETE SET NULL, are treated as part of the SQL command that caused them (note that such actions are never deferred)\&. Relevant triggers on the affected table will be fired, so that this provides another way in which an SQL command might fire triggers not directly matching its type\&. In simple cases, triggers that request transition relations will see all changes caused in their table by a single original SQL command as a single transition relation\&. However, there are cases in which the presence of an +AFTER ROW +trigger that requests transition relations will cause the foreign\-key enforcement actions triggered by a single SQL command to be split into multiple steps, each with its own transition relation(s)\&. In such cases, any statement\-level triggers that are present will be fired once per creation of a transition relation set, ensuring that the triggers see each affected row in a transition relation once and only once\&. +.PP +Statement\-level triggers on a view are fired only if the action on the view is handled by a row\-level +INSTEAD OF +trigger\&. If the action is handled by an +INSTEAD +rule, then whatever statements are emitted by the rule are executed in place of the original statement naming the view, so that the triggers that will be fired are those on tables named in the replacement statements\&. Similarly, if the view is automatically updatable, then the action is handled by automatically rewriting the statement into an action on the view\*(Aqs base table, so that the base table\*(Aqs statement\-level triggers are the ones that are fired\&. +.PP +Modifying a partitioned table or a table with inheritance children fires statement\-level triggers attached to the explicitly named table, but not statement\-level triggers for its partitions or child tables\&. In contrast, row\-level triggers are fired on the rows in affected partitions or child tables, even if they are not explicitly named in the query\&. If a statement\-level trigger has been defined with transition relations named by a +REFERENCING +clause, then before and after images of rows are visible from all affected partitions or child tables\&. In the case of inheritance children, the row images include only columns that are present in the table that the trigger is attached to\&. +.PP +Currently, row\-level triggers with transition relations cannot be defined on partitions or inheritance child tables\&. Also, triggers on partitioned tables may not be +INSTEAD OF\&. +.PP +Currently, the +OR REPLACE +option is not supported for constraint triggers\&. +.PP +Replacing an existing trigger within a transaction that has already performed updating actions on the trigger\*(Aqs table is not recommended\&. Trigger firing decisions, or portions of firing decisions, that have already been made will not be reconsidered, so the effects could be surprising\&. +.PP +There are a few built\-in trigger functions that can be used to solve common problems without having to write your own trigger code; see +Section\ \&9.28\&. +.SH "EXAMPLES" +.PP +Execute the function +\fBcheck_account_update\fR +whenever a row of the table +accounts +is about to be updated: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRIGGER check_update + BEFORE UPDATE ON accounts + FOR EACH ROW + EXECUTE FUNCTION check_account_update(); +.fi +.if n \{\ +.RE +.\} +.sp +Modify that trigger definition to only execute the function if column +balance +is specified as a target in the +\fBUPDATE\fR +command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE OR REPLACE TRIGGER check_update + BEFORE UPDATE OF balance ON accounts + FOR EACH ROW + EXECUTE FUNCTION check_account_update(); +.fi +.if n \{\ +.RE +.\} +.sp +This form only executes the function if column +balance +has in fact changed value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRIGGER check_update + BEFORE UPDATE ON accounts + FOR EACH ROW + WHEN (OLD\&.balance IS DISTINCT FROM NEW\&.balance) + EXECUTE FUNCTION check_account_update(); +.fi +.if n \{\ +.RE +.\} +.sp +Call a function to log updates of +accounts, but only if something changed: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRIGGER log_update + AFTER UPDATE ON accounts + FOR EACH ROW + WHEN (OLD\&.* IS DISTINCT FROM NEW\&.*) + EXECUTE FUNCTION log_account_update(); +.fi +.if n \{\ +.RE +.\} +.sp +Execute the function +\fBview_insert_row\fR +for each row to insert rows into the tables underlying a view: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRIGGER view_insert + INSTEAD OF INSERT ON my_view + FOR EACH ROW + EXECUTE FUNCTION view_insert_row(); +.fi +.if n \{\ +.RE +.\} +.sp +Execute the function +\fBcheck_transfer_balances_to_zero\fR +for each statement to confirm that the +transfer +rows offset to a net of zero: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRIGGER transfer_insert + AFTER INSERT ON transfer + REFERENCING NEW TABLE AS inserted + FOR EACH STATEMENT + EXECUTE FUNCTION check_transfer_balances_to_zero(); +.fi +.if n \{\ +.RE +.\} +.sp +Execute the function +\fBcheck_matching_pairs\fR +for each row to confirm that changes are made to matching pairs at the same time (by the same statement): +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TRIGGER paired_items_update + AFTER UPDATE ON paired_items + REFERENCING NEW TABLE AS newtab OLD TABLE AS oldtab + FOR EACH ROW + EXECUTE FUNCTION check_matching_pairs(); +.fi +.if n \{\ +.RE +.\} +.PP +Section\ \&39.4 +contains a complete example of a trigger function written in C\&. +.SH "COMPATIBILITY" +.PP +The +\fBCREATE TRIGGER\fR +statement in +PostgreSQL +implements a subset of the +SQL +standard\&. The following functionalities are currently missing: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +While transition table names for +AFTER +triggers are specified using the +REFERENCING +clause in the standard way, the row variables used in +FOR EACH ROW +triggers may not be specified in a +REFERENCING +clause\&. They are available in a manner that is dependent on the language in which the trigger function is written, but is fixed for any one language\&. Some languages effectively behave as though there is a +REFERENCING +clause containing +OLD ROW AS OLD NEW ROW AS NEW\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The standard allows transition tables to be used with column\-specific +UPDATE +triggers, but then the set of rows that should be visible in the transition tables depends on the trigger\*(Aqs column list\&. This is not currently implemented by +PostgreSQL\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +PostgreSQL +only allows the execution of a user\-defined function for the triggered action\&. The standard allows the execution of a number of other SQL commands, such as +\fBCREATE TABLE\fR, as the triggered action\&. This limitation is not hard to work around by creating a user\-defined function that executes the desired commands\&. +.RE +.PP +SQL specifies that multiple triggers should be fired in time\-of\-creation order\&. +PostgreSQL +uses name order, which was judged to be more convenient\&. +.PP +SQL specifies that +BEFORE DELETE +triggers on cascaded deletes fire +\fIafter\fR +the cascaded +DELETE +completes\&. The +PostgreSQL +behavior is for +BEFORE DELETE +to always fire before the delete action, even a cascading one\&. This is considered more consistent\&. There is also nonstandard behavior if +BEFORE +triggers modify rows or prevent updates during an update that is caused by a referential action\&. This can lead to constraint violations or stored data that does not honor the referential constraint\&. +.PP +The ability to specify multiple actions for a single trigger using +OR +is a +PostgreSQL +extension of the SQL standard\&. +.PP +The ability to fire triggers for +\fBTRUNCATE\fR +is a +PostgreSQL +extension of the SQL standard, as is the ability to define statement\-level triggers on views\&. +.PP +\fBCREATE CONSTRAINT TRIGGER\fR +is a +PostgreSQL +extension of the +SQL +standard\&. So is the +OR REPLACE +option\&. +.SH "SEE ALSO" +ALTER TRIGGER (\fBALTER_TRIGGER\fR(7)), DROP TRIGGER (\fBDROP_TRIGGER\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), SET CONSTRAINTS (\fBSET_CONSTRAINTS\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_TYPE.7 b/doc/src/sgml/man7/CREATE_TYPE.7 new file mode 100644 index 0000000..318c4ce --- /dev/null +++ b/doc/src/sgml/man7/CREATE_TYPE.7 @@ -0,0 +1,733 @@ +'\" t +.\" Title: CREATE TYPE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE TYPE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_TYPE \- define a new data type +.SH "SYNOPSIS" +.sp +.nf +CREATE TYPE \fIname\fR AS + ( [ \fIattribute_name\fR \fIdata_type\fR [ COLLATE \fIcollation\fR ] [, \&.\&.\&. ] ] ) + +CREATE TYPE \fIname\fR AS ENUM + ( [ \*(Aq\fIlabel\fR\*(Aq [, \&.\&.\&. ] ] ) + +CREATE TYPE \fIname\fR AS RANGE ( + SUBTYPE = \fIsubtype\fR + [ , SUBTYPE_OPCLASS = \fIsubtype_operator_class\fR ] + [ , COLLATION = \fIcollation\fR ] + [ , CANONICAL = \fIcanonical_function\fR ] + [ , SUBTYPE_DIFF = \fIsubtype_diff_function\fR ] + [ , MULTIRANGE_TYPE_NAME = \fImultirange_type_name\fR ] +) + +CREATE TYPE \fIname\fR ( + INPUT = \fIinput_function\fR, + OUTPUT = \fIoutput_function\fR + [ , RECEIVE = \fIreceive_function\fR ] + [ , SEND = \fIsend_function\fR ] + [ , TYPMOD_IN = \fItype_modifier_input_function\fR ] + [ , TYPMOD_OUT = \fItype_modifier_output_function\fR ] + [ , ANALYZE = \fIanalyze_function\fR ] + [ , SUBSCRIPT = \fIsubscript_function\fR ] + [ , INTERNALLENGTH = { \fIinternallength\fR | VARIABLE } ] + [ , PASSEDBYVALUE ] + [ , ALIGNMENT = \fIalignment\fR ] + [ , STORAGE = \fIstorage\fR ] + [ , LIKE = \fIlike_type\fR ] + [ , CATEGORY = \fIcategory\fR ] + [ , PREFERRED = \fIpreferred\fR ] + [ , DEFAULT = \fIdefault\fR ] + [ , ELEMENT = \fIelement\fR ] + [ , DELIMITER = \fIdelimiter\fR ] + [ , COLLATABLE = \fIcollatable\fR ] +) + +CREATE TYPE \fIname\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE TYPE\fR +registers a new data type for use in the current database\&. The user who defines a type becomes its owner\&. +.PP +If a schema name is given then the type is created in the specified schema\&. Otherwise it is created in the current schema\&. The type name must be distinct from the name of any existing type or domain in the same schema\&. (Because tables have associated data types, the type name must also be distinct from the name of any existing table in the same schema\&.) +.PP +There are five forms of +\fBCREATE TYPE\fR, as shown in the syntax synopsis above\&. They respectively create a +composite type, an +enum type, a +range type, a +base type, or a +shell type\&. The first four of these are discussed in turn below\&. A shell type is simply a placeholder for a type to be defined later; it is created by issuing +\fBCREATE TYPE\fR +with no parameters except for the type name\&. Shell types are needed as forward references when creating range types and base types, as discussed in those sections\&. +.SS "Composite Types" +.PP +The first form of +\fBCREATE TYPE\fR +creates a composite type\&. The composite type is specified by a list of attribute names and data types\&. An attribute\*(Aqs collation can be specified too, if its data type is collatable\&. A composite type is essentially the same as the row type of a table, but using +\fBCREATE TYPE\fR +avoids the need to create an actual table when all that is wanted is to define a type\&. A stand\-alone composite type is useful, for example, as the argument or return type of a function\&. +.PP +To be able to create a composite type, you must have +USAGE +privilege on all attribute types\&. +.SS "Enumerated Types" +.PP +The second form of +\fBCREATE TYPE\fR +creates an enumerated (enum) type, as described in +Section\ \&8.7\&. Enum types take a list of quoted labels, each of which must be less than +NAMEDATALEN +bytes long (64 bytes in a standard +PostgreSQL +build)\&. (It is possible to create an enumerated type with zero labels, but such a type cannot be used to hold values before at least one label is added using +\fBALTER TYPE\fR\&.) +.SS "Range Types" +.PP +The third form of +\fBCREATE TYPE\fR +creates a new range type, as described in +Section\ \&8.17\&. +.PP +The range type\*(Aqs +\fIsubtype\fR +can be any type with an associated b\-tree operator class (to determine the ordering of values for the range type)\&. Normally the subtype\*(Aqs default b\-tree operator class is used to determine ordering; to use a non\-default operator class, specify its name with +\fIsubtype_opclass\fR\&. If the subtype is collatable, and you want to use a non\-default collation in the range\*(Aqs ordering, specify the desired collation with the +\fIcollation\fR +option\&. +.PP +The optional +\fIcanonical\fR +function must take one argument of the range type being defined, and return a value of the same type\&. This is used to convert range values to a canonical form, when applicable\&. See +Section\ \&8.17.8 +for more information\&. Creating a +\fIcanonical\fR +function is a bit tricky, since it must be defined before the range type can be declared\&. To do this, you must first create a shell type, which is a placeholder type that has no properties except a name and an owner\&. This is done by issuing the command +CREATE TYPE \fIname\fR, with no additional parameters\&. Then the function can be declared using the shell type as argument and result, and finally the range type can be declared using the same name\&. This automatically replaces the shell type entry with a valid range type\&. +.PP +The optional +\fIsubtype_diff\fR +function must take two values of the +\fIsubtype\fR +type as argument, and return a +double precision +value representing the difference between the two given values\&. While this is optional, providing it allows much greater efficiency of GiST indexes on columns of the range type\&. See +Section\ \&8.17.8 +for more information\&. +.PP +The optional +\fImultirange_type_name\fR +parameter specifies the name of the corresponding multirange type\&. If not specified, this name is chosen automatically as follows\&. If the range type name contains the substring +range, then the multirange type name is formed by replacement of the +range +substring with +multirange +in the range type name\&. Otherwise, the multirange type name is formed by appending a +_multirange +suffix to the range type name\&. +.SS "Base Types" +.PP +The fourth form of +\fBCREATE TYPE\fR +creates a new base type (scalar type)\&. To create a new base type, you must be a superuser\&. (This restriction is made because an erroneous type definition could confuse or even crash the server\&.) +.PP +The parameters can appear in any order, not only that illustrated above, and most are optional\&. You must register two or more functions (using +\fBCREATE FUNCTION\fR) before defining the type\&. The support functions +\fIinput_function\fR +and +\fIoutput_function\fR +are required, while the functions +\fIreceive_function\fR, +\fIsend_function\fR, +\fItype_modifier_input_function\fR, +\fItype_modifier_output_function\fR, +\fIanalyze_function\fR, and +\fIsubscript_function\fR +are optional\&. Generally these functions have to be coded in C or another low\-level language\&. +.PP +The +\fIinput_function\fR +converts the type\*(Aqs external textual representation to the internal representation used by the operators and functions defined for the type\&. +\fIoutput_function\fR +performs the reverse transformation\&. The input function can be declared as taking one argument of type +cstring, or as taking three arguments of types +cstring, +oid, +integer\&. The first argument is the input text as a C string, the second argument is the type\*(Aqs own OID (except for array types, which instead receive their element type\*(Aqs OID), and the third is the +typmod +of the destination column, if known (\-1 will be passed if not)\&. The input function must return a value of the data type itself\&. Usually, an input function should be declared STRICT; if it is not, it will be called with a NULL first parameter when reading a NULL input value\&. The function must still return NULL in this case, unless it raises an error\&. (This case is mainly meant to support domain input functions, which might need to reject NULL inputs\&.) The output function must be declared as taking one argument of the new data type\&. The output function must return type +cstring\&. Output functions are not invoked for NULL values\&. +.PP +The optional +\fIreceive_function\fR +converts the type\*(Aqs external binary representation to the internal representation\&. If this function is not supplied, the type cannot participate in binary input\&. The binary representation should be chosen to be cheap to convert to internal form, while being reasonably portable\&. (For example, the standard integer data types use network byte order as the external binary representation, while the internal representation is in the machine\*(Aqs native byte order\&.) The receive function should perform adequate checking to ensure that the value is valid\&. The receive function can be declared as taking one argument of type +internal, or as taking three arguments of types +internal, +oid, +integer\&. The first argument is a pointer to a +StringInfo +buffer holding the received byte string; the optional arguments are the same as for the text input function\&. The receive function must return a value of the data type itself\&. Usually, a receive function should be declared STRICT; if it is not, it will be called with a NULL first parameter when reading a NULL input value\&. The function must still return NULL in this case, unless it raises an error\&. (This case is mainly meant to support domain receive functions, which might need to reject NULL inputs\&.) Similarly, the optional +\fIsend_function\fR +converts from the internal representation to the external binary representation\&. If this function is not supplied, the type cannot participate in binary output\&. The send function must be declared as taking one argument of the new data type\&. The send function must return type +bytea\&. Send functions are not invoked for NULL values\&. +.PP +You should at this point be wondering how the input and output functions can be declared to have results or arguments of the new type, when they have to be created before the new type can be created\&. The answer is that the type should first be defined as a +shell type, which is a placeholder type that has no properties except a name and an owner\&. This is done by issuing the command +CREATE TYPE \fIname\fR, with no additional parameters\&. Then the C I/O functions can be defined referencing the shell type\&. Finally, +\fBCREATE TYPE\fR +with a full definition replaces the shell entry with a complete, valid type definition, after which the new type can be used normally\&. +.PP +The optional +\fItype_modifier_input_function\fR +and +\fItype_modifier_output_function\fR +are needed if the type supports modifiers, that is optional constraints attached to a type declaration, such as +char(5) +or +numeric(30,2)\&. +PostgreSQL +allows user\-defined types to take one or more simple constants or identifiers as modifiers\&. However, this information must be capable of being packed into a single non\-negative integer value for storage in the system catalogs\&. The +\fItype_modifier_input_function\fR +is passed the declared modifier(s) in the form of a +cstring +array\&. It must check the values for validity (throwing an error if they are wrong), and if they are correct, return a single non\-negative +integer +value that will be stored as the column +\(lqtypmod\(rq\&. Type modifiers will be rejected if the type does not have a +\fItype_modifier_input_function\fR\&. The +\fItype_modifier_output_function\fR +converts the internal integer typmod value back to the correct form for user display\&. It must return a +cstring +value that is the exact string to append to the type name; for example +numeric\*(Aqs function might return +(30,2)\&. It is allowed to omit the +\fItype_modifier_output_function\fR, in which case the default display format is just the stored typmod integer value enclosed in parentheses\&. +.PP +The optional +\fIanalyze_function\fR +performs type\-specific statistics collection for columns of the data type\&. By default, +\fBANALYZE\fR +will attempt to gather statistics using the type\*(Aqs +\(lqequals\(rq +and +\(lqless\-than\(rq +operators, if there is a default b\-tree operator class for the type\&. For non\-scalar types this behavior is likely to be unsuitable, so it can be overridden by specifying a custom analysis function\&. The analysis function must be declared to take a single argument of type +internal, and return a +boolean +result\&. The detailed API for analysis functions appears in +src/include/commands/vacuum\&.h\&. +.PP +The optional +\fIsubscript_function\fR +allows the data type to be subscripted in SQL commands\&. Specifying this function does not cause the type to be considered a +\(lqtrue\(rq +array type; for example, it will not be a candidate for the result type of +ARRAY[] +constructs\&. But if subscripting a value of the type is a natural notation for extracting data from it, then a +\fIsubscript_function\fR +can be written to define what that means\&. The subscript function must be declared to take a single argument of type +internal, and return an +internal +result, which is a pointer to a struct of methods (functions) that implement subscripting\&. The detailed API for subscript functions appears in +src/include/nodes/subscripting\&.h\&. It may also be useful to read the array implementation in +src/backend/utils/adt/arraysubs\&.c, or the simpler code in +contrib/hstore/hstore_subs\&.c\&. Additional information appears in +Array Types +below\&. +.PP +While the details of the new type\*(Aqs internal representation are only known to the I/O functions and other functions you create to work with the type, there are several properties of the internal representation that must be declared to +PostgreSQL\&. Foremost of these is +\fIinternallength\fR\&. Base data types can be fixed\-length, in which case +\fIinternallength\fR +is a positive integer, or variable\-length, indicated by setting +\fIinternallength\fR +to +VARIABLE\&. (Internally, this is represented by setting +typlen +to \-1\&.) The internal representation of all variable\-length types must start with a 4\-byte integer giving the total length of this value of the type\&. (Note that the length field is often encoded, as described in +Section\ \&73.2; it\*(Aqs unwise to access it directly\&.) +.PP +The optional flag +PASSEDBYVALUE +indicates that values of this data type are passed by value, rather than by reference\&. Types passed by value must be fixed\-length, and their internal representation cannot be larger than the size of the +Datum +type (4 bytes on some machines, 8 bytes on others)\&. +.PP +The +\fIalignment\fR +parameter specifies the storage alignment required for the data type\&. The allowed values equate to alignment on 1, 2, 4, or 8 byte boundaries\&. Note that variable\-length types must have an alignment of at least 4, since they necessarily contain an +int4 +as their first component\&. +.PP +The +\fIstorage\fR +parameter allows selection of storage strategies for variable\-length data types\&. (Only +plain +is allowed for fixed\-length types\&.) +plain +specifies that data of the type will always be stored in\-line and not compressed\&. +extended +specifies that the system will first try to compress a long data value, and will move the value out of the main table row if it\*(Aqs still too long\&. +external +allows the value to be moved out of the main table, but the system will not try to compress it\&. +main +allows compression, but discourages moving the value out of the main table\&. (Data items with this storage strategy might still be moved out of the main table if there is no other way to make a row fit, but they will be kept in the main table preferentially over +extended +and +external +items\&.) +.PP +All +\fIstorage\fR +values other than +plain +imply that the functions of the data type can handle values that have been +toasted, as described in +Section\ \&73.2 +and +Section\ \&38.13.1\&. The specific other value given merely determines the default TOAST storage strategy for columns of a toastable data type; users can pick other strategies for individual columns using +ALTER TABLE SET STORAGE\&. +.PP +The +\fIlike_type\fR +parameter provides an alternative method for specifying the basic representation properties of a data type: copy them from some existing type\&. The values of +\fIinternallength\fR, +\fIpassedbyvalue\fR, +\fIalignment\fR, and +\fIstorage\fR +are copied from the named type\&. (It is possible, though usually undesirable, to override some of these values by specifying them along with the +LIKE +clause\&.) Specifying representation this way is especially useful when the low\-level implementation of the new type +\(lqpiggybacks\(rq +on an existing type in some fashion\&. +.PP +The +\fIcategory\fR +and +\fIpreferred\fR +parameters can be used to help control which implicit cast will be applied in ambiguous situations\&. Each data type belongs to a category named by a single ASCII character, and each type is either +\(lqpreferred\(rq +or not within its category\&. The parser will prefer casting to preferred types (but only from other types within the same category) when this rule is helpful in resolving overloaded functions or operators\&. For more details see +Chapter\ \&10\&. For types that have no implicit casts to or from any other types, it is sufficient to leave these settings at the defaults\&. However, for a group of related types that have implicit casts, it is often helpful to mark them all as belonging to a category and select one or two of the +\(lqmost general\(rq +types as being preferred within the category\&. The +\fIcategory\fR +parameter is especially useful when adding a user\-defined type to an existing built\-in category, such as the numeric or string types\&. However, it is also possible to create new entirely\-user\-defined type categories\&. Select any ASCII character other than an upper\-case letter to name such a category\&. +.PP +A default value can be specified, in case a user wants columns of the data type to default to something other than the null value\&. Specify the default with the +DEFAULT +key word\&. (Such a default can be overridden by an explicit +DEFAULT +clause attached to a particular column\&.) +.PP +To indicate that a type is a fixed\-length array type, specify the type of the array elements using the +ELEMENT +key word\&. For example, to define an array of 4\-byte integers (int4), specify +ELEMENT = int4\&. For more details, see +Array Types +below\&. +.PP +To indicate the delimiter to be used between values in the external representation of arrays of this type, +\fIdelimiter\fR +can be set to a specific character\&. The default delimiter is the comma (,)\&. Note that the delimiter is associated with the array element type, not the array type itself\&. +.PP +If the optional Boolean parameter +\fIcollatable\fR +is true, column definitions and expressions of the type may carry collation information through use of the +COLLATE +clause\&. It is up to the implementations of the functions operating on the type to actually make use of the collation information; this does not happen automatically merely by marking the type collatable\&. +.SS "Array Types" +.PP +Whenever a user\-defined type is created, +PostgreSQL +automatically creates an associated array type, whose name consists of the element type\*(Aqs name prepended with an underscore, and truncated if necessary to keep it less than +NAMEDATALEN +bytes long\&. (If the name so generated collides with an existing type name, the process is repeated until a non\-colliding name is found\&.) This implicitly\-created array type is variable length and uses the built\-in input and output functions +array_in +and +array_out\&. Furthermore, this type is what the system uses for constructs such as +ARRAY[] +over the user\-defined type\&. The array type tracks any changes in its element type\*(Aqs owner or schema, and is dropped if the element type is\&. +.PP +You might reasonably ask why there is an +\fBELEMENT\fR +option, if the system makes the correct array type automatically\&. The main case where it\*(Aqs useful to use +\fBELEMENT\fR +is when you are making a fixed\-length type that happens to be internally an array of a number of identical things, and you want to allow these things to be accessed directly by subscripting, in addition to whatever operations you plan to provide for the type as a whole\&. For example, type +point +is represented as just two floating\-point numbers, which can be accessed using +point[0] +and +point[1]\&. Note that this facility only works for fixed\-length types whose internal form is exactly a sequence of identical fixed\-length fields\&. For historical reasons (i\&.e\&., this is clearly wrong but it\*(Aqs far too late to change it), subscripting of fixed\-length array types starts from zero, rather than from one as for variable\-length arrays\&. +.PP +Specifying the +\fBSUBSCRIPT\fR +option allows a data type to be subscripted, even though the system does not otherwise regard it as an array type\&. The behavior just described for fixed\-length arrays is actually implemented by the +\fBSUBSCRIPT\fR +handler function +\fBraw_array_subscript_handler\fR, which is used automatically if you specify +\fBELEMENT\fR +for a fixed\-length type without also writing +\fBSUBSCRIPT\fR\&. +.PP +When specifying a custom +\fBSUBSCRIPT\fR +function, it is not necessary to specify +\fBELEMENT\fR +unless the +\fBSUBSCRIPT\fR +handler function needs to consult +typelem +to find out what to return\&. Be aware that specifying +\fBELEMENT\fR +causes the system to assume that the new type contains, or is somehow physically dependent on, the element type; thus for example changing properties of the element type won\*(Aqt be allowed if there are any columns of the dependent type\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of a type to be created\&. +.RE +.PP +\fIattribute_name\fR +.RS 4 +The name of an attribute (column) for the composite type\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The name of an existing data type to become a column of the composite type\&. +.RE +.PP +\fIcollation\fR +.RS 4 +The name of an existing collation to be associated with a column of a composite type, or with a range type\&. +.RE +.PP +\fIlabel\fR +.RS 4 +A string literal representing the textual label associated with one value of an enum type\&. +.RE +.PP +\fIsubtype\fR +.RS 4 +The name of the element type that the range type will represent ranges of\&. +.RE +.PP +\fIsubtype_operator_class\fR +.RS 4 +The name of a b\-tree operator class for the subtype\&. +.RE +.PP +\fIcanonical_function\fR +.RS 4 +The name of the canonicalization function for the range type\&. +.RE +.PP +\fIsubtype_diff_function\fR +.RS 4 +The name of a difference function for the subtype\&. +.RE +.PP +\fImultirange_type_name\fR +.RS 4 +The name of the corresponding multirange type\&. +.RE +.PP +\fIinput_function\fR +.RS 4 +The name of a function that converts data from the type\*(Aqs external textual form to its internal form\&. +.RE +.PP +\fIoutput_function\fR +.RS 4 +The name of a function that converts data from the type\*(Aqs internal form to its external textual form\&. +.RE +.PP +\fIreceive_function\fR +.RS 4 +The name of a function that converts data from the type\*(Aqs external binary form to its internal form\&. +.RE +.PP +\fIsend_function\fR +.RS 4 +The name of a function that converts data from the type\*(Aqs internal form to its external binary form\&. +.RE +.PP +\fItype_modifier_input_function\fR +.RS 4 +The name of a function that converts an array of modifier(s) for the type into internal form\&. +.RE +.PP +\fItype_modifier_output_function\fR +.RS 4 +The name of a function that converts the internal form of the type\*(Aqs modifier(s) to external textual form\&. +.RE +.PP +\fIanalyze_function\fR +.RS 4 +The name of a function that performs statistical analysis for the data type\&. +.RE +.PP +\fIsubscript_function\fR +.RS 4 +The name of a function that defines what subscripting a value of the data type does\&. +.RE +.PP +\fIinternallength\fR +.RS 4 +A numeric constant that specifies the length in bytes of the new type\*(Aqs internal representation\&. The default assumption is that it is variable\-length\&. +.RE +.PP +\fIalignment\fR +.RS 4 +The storage alignment requirement of the data type\&. If specified, it must be +char, +int2, +int4, or +double; the default is +int4\&. +.RE +.PP +\fIstorage\fR +.RS 4 +The storage strategy for the data type\&. If specified, must be +plain, +external, +extended, or +main; the default is +plain\&. +.RE +.PP +\fIlike_type\fR +.RS 4 +The name of an existing data type that the new type will have the same representation as\&. The values of +\fIinternallength\fR, +\fIpassedbyvalue\fR, +\fIalignment\fR, and +\fIstorage\fR +are copied from that type, unless overridden by explicit specification elsewhere in this +\fBCREATE TYPE\fR +command\&. +.RE +.PP +\fIcategory\fR +.RS 4 +The category code (a single ASCII character) for this type\&. The default is +\*(AqU\*(Aq +for +\(lquser\-defined type\(rq\&. Other standard category codes can be found in +Table\ \&53.65\&. You may also choose other ASCII characters in order to create custom categories\&. +.RE +.PP +\fIpreferred\fR +.RS 4 +True if this type is a preferred type within its type category, else false\&. The default is false\&. Be very careful about creating a new preferred type within an existing type category, as this could cause surprising changes in behavior\&. +.RE +.PP +\fIdefault\fR +.RS 4 +The default value for the data type\&. If this is omitted, the default is null\&. +.RE +.PP +\fIelement\fR +.RS 4 +The type being created is an array; this specifies the type of the array elements\&. +.RE +.PP +\fIdelimiter\fR +.RS 4 +The delimiter character to be used between values in arrays made of this type\&. +.RE +.PP +\fIcollatable\fR +.RS 4 +True if this type\*(Aqs operations can use collation information\&. The default is false\&. +.RE +.SH "NOTES" +.PP +Because there are no restrictions on use of a data type once it\*(Aqs been created, creating a base type or range type is tantamount to granting public execute permission on the functions mentioned in the type definition\&. This is usually not an issue for the sorts of functions that are useful in a type definition\&. But you might want to think twice before designing a type in a way that would require +\(lqsecret\(rq +information to be used while converting it to or from external form\&. +.PP +Before +PostgreSQL +version 8\&.3, the name of a generated array type was always exactly the element type\*(Aqs name with one underscore character (_) prepended\&. (Type names were therefore restricted in length to one fewer character than other names\&.) While this is still usually the case, the array type name may vary from this in case of maximum\-length names or collisions with user type names that begin with underscore\&. Writing code that depends on this convention is therefore deprecated\&. Instead, use +pg_type\&.typarray +to locate the array type associated with a given type\&. +.PP +It may be advisable to avoid using type and table names that begin with underscore\&. While the server will change generated array type names to avoid collisions with user\-given names, there is still risk of confusion, particularly with old client software that may assume that type names beginning with underscores always represent arrays\&. +.PP +Before +PostgreSQL +version 8\&.2, the shell\-type creation syntax +CREATE TYPE \fIname\fR +did not exist\&. The way to create a new base type was to create its input function first\&. In this approach, +PostgreSQL +will first see the name of the new data type as the return type of the input function\&. The shell type is implicitly created in this situation, and then it can be referenced in the definitions of the remaining I/O functions\&. This approach still works, but is deprecated and might be disallowed in some future release\&. Also, to avoid accidentally cluttering the catalogs with shell types as a result of simple typos in function definitions, a shell type will only be made this way when the input function is written in C\&. +.SH "EXAMPLES" +.PP +This example creates a composite type and uses it in a function definition: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE compfoo AS (f1 int, f2 text); + +CREATE FUNCTION getfoo() RETURNS SETOF compfoo AS $$ + SELECT fooid, fooname FROM foo +$$ LANGUAGE SQL; +.fi +.if n \{\ +.RE +.\} +.PP +This example creates an enumerated type and uses it in a table definition: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE bug_status AS ENUM (\*(Aqnew\*(Aq, \*(Aqopen\*(Aq, \*(Aqclosed\*(Aq); + +CREATE TABLE bug ( + id serial, + description text, + status bug_status +); +.fi +.if n \{\ +.RE +.\} +.PP +This example creates a range type: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE float8_range AS RANGE (subtype = float8, subtype_diff = float8mi); +.fi +.if n \{\ +.RE +.\} +.PP +This example creates the base data type +box +and then uses the type in a table definition: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE box; + +CREATE FUNCTION my_box_in_function(cstring) RETURNS box AS \&.\&.\&. ; +CREATE FUNCTION my_box_out_function(box) RETURNS cstring AS \&.\&.\&. ; + +CREATE TYPE box ( + INTERNALLENGTH = 16, + INPUT = my_box_in_function, + OUTPUT = my_box_out_function +); + +CREATE TABLE myboxes ( + id integer, + description box +); +.fi +.if n \{\ +.RE +.\} +.PP +If the internal structure of +box +were an array of four +float4 +elements, we might instead use: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE box ( + INTERNALLENGTH = 16, + INPUT = my_box_in_function, + OUTPUT = my_box_out_function, + ELEMENT = float4 +); +.fi +.if n \{\ +.RE +.\} +.sp +which would allow a box value\*(Aqs component numbers to be accessed by subscripting\&. Otherwise the type behaves the same as before\&. +.PP +This example creates a large object type and uses it in a table definition: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE TYPE bigobj ( + INPUT = lo_filein, OUTPUT = lo_fileout, + INTERNALLENGTH = VARIABLE +); +CREATE TABLE big_objs ( + id integer, + obj bigobj +); +.fi +.if n \{\ +.RE +.\} +.PP +More examples, including suitable input and output functions, are in +Section\ \&38.13\&. +.SH "COMPATIBILITY" +.PP +The first form of the +\fBCREATE TYPE\fR +command, which creates a composite type, conforms to the +SQL +standard\&. The other forms are +PostgreSQL +extensions\&. The +\fBCREATE TYPE\fR +statement in the +SQL +standard also defines other forms that are not implemented in +PostgreSQL\&. +.PP +The ability to create a composite type with zero attributes is a +PostgreSQL\-specific deviation from the standard (analogous to the same case in +\fBCREATE TABLE\fR)\&. +.SH "SEE ALSO" +ALTER TYPE (\fBALTER_TYPE\fR(7)), CREATE DOMAIN (\fBCREATE_DOMAIN\fR(7)), CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), DROP TYPE (\fBDROP_TYPE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_USER.7 b/doc/src/sgml/man7/CREATE_USER.7 new file mode 100644 index 0000000..04dc528 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_USER.7 @@ -0,0 +1,75 @@ +'\" t +.\" Title: CREATE USER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE USER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_USER \- define a new database role +.SH "SYNOPSIS" +.sp +.nf +CREATE USER \fIname\fR [ [ WITH ] \fIoption\fR [ \&.\&.\&. ] ] + +where \fIoption\fR can be: + + SUPERUSER | NOSUPERUSER + | CREATEDB | NOCREATEDB + | CREATEROLE | NOCREATEROLE + | INHERIT | NOINHERIT + | LOGIN | NOLOGIN + | REPLICATION | NOREPLICATION + | BYPASSRLS | NOBYPASSRLS + | CONNECTION LIMIT \fIconnlimit\fR + | [ ENCRYPTED ] PASSWORD \*(Aq\fIpassword\fR\*(Aq | PASSWORD NULL + | VALID UNTIL \*(Aq\fItimestamp\fR\*(Aq + | IN ROLE \fIrole_name\fR [, \&.\&.\&.] + | IN GROUP \fIrole_name\fR [, \&.\&.\&.] + | ROLE \fIrole_name\fR [, \&.\&.\&.] + | ADMIN \fIrole_name\fR [, \&.\&.\&.] + | USER \fIrole_name\fR [, \&.\&.\&.] + | SYSID \fIuid\fR +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE USER\fR +is now an alias for +\fBCREATE ROLE\fR\&. The only difference is that when the command is spelled +\fBCREATE USER\fR, +LOGIN +is assumed by default, whereas +NOLOGIN +is assumed when the command is spelled +\fBCREATE ROLE\fR\&. +.SH "COMPATIBILITY" +.PP +The +\fBCREATE USER\fR +statement is a +PostgreSQL +extension\&. The SQL standard leaves the definition of users to the implementation\&. +.SH "SEE ALSO" +CREATE ROLE (\fBCREATE_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_USER_MAPPING.7 b/doc/src/sgml/man7/CREATE_USER_MAPPING.7 new file mode 100644 index 0000000..c9f0ee2 --- /dev/null +++ b/doc/src/sgml/man7/CREATE_USER_MAPPING.7 @@ -0,0 +1,94 @@ +'\" t +.\" Title: CREATE USER MAPPING +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE USER MAPPING" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_USER_MAPPING \- define a new mapping of a user to a foreign server +.SH "SYNOPSIS" +.sp +.nf +CREATE USER MAPPING [ IF NOT EXISTS ] FOR { \fIuser_name\fR | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC } + SERVER \fIserver_name\fR + [ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [ , \&.\&.\&. ] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE USER MAPPING\fR +defines a mapping of a user to a foreign server\&. A user mapping typically encapsulates connection information that a foreign\-data wrapper uses together with the information encapsulated by a foreign server to access an external data resource\&. +.PP +The owner of a foreign server can create user mappings for that server for any user\&. Also, a user can create a user mapping for their own user name if +USAGE +privilege on the server has been granted to the user\&. +.SH "PARAMETERS" +.PP +IF NOT EXISTS +.RS 4 +Do not throw an error if a mapping of the given user to the given foreign server already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing user mapping is anything like the one that would have been created\&. +.RE +.PP +\fIuser_name\fR +.RS 4 +The name of an existing user that is mapped to foreign server\&. +CURRENT_ROLE, +CURRENT_USER, and +USER +match the name of the current user\&. When +PUBLIC +is specified, a so\-called public mapping is created that is used when no user\-specific mapping is applicable\&. +.RE +.PP +\fIserver_name\fR +.RS 4 +The name of an existing server for which the user mapping is to be created\&. +.RE +.PP +OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) +.RS 4 +This clause specifies the options of the user mapping\&. The options typically define the actual user name and password of the mapping\&. Option names must be unique\&. The allowed option names and values are specific to the server\*(Aqs foreign\-data wrapper\&. +.RE +.SH "EXAMPLES" +.PP +Create a user mapping for user +bob, server +foo: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE USER MAPPING FOR bob SERVER foo OPTIONS (user \*(Aqbob\*(Aq, password \*(Aqsecret\*(Aq); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBCREATE USER MAPPING\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. +.SH "SEE ALSO" +ALTER USER MAPPING (\fBALTER_USER_MAPPING\fR(7)), DROP USER MAPPING (\fBDROP_USER_MAPPING\fR(7)), CREATE FOREIGN DATA WRAPPER (\fBCREATE_FOREIGN_DATA_WRAPPER\fR(7)), CREATE SERVER (\fBCREATE_SERVER\fR(7)) diff --git a/doc/src/sgml/man7/CREATE_VIEW.7 b/doc/src/sgml/man7/CREATE_VIEW.7 new file mode 100644 index 0000000..b40752e --- /dev/null +++ b/doc/src/sgml/man7/CREATE_VIEW.7 @@ -0,0 +1,545 @@ +'\" t +.\" Title: CREATE VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "CREATE VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +CREATE_VIEW \- define a new view +.SH "SYNOPSIS" +.sp +.nf +CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW \fIname\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] + [ WITH ( \fIview_option_name\fR [= \fIview_option_value\fR] [, \&.\&.\&. ] ) ] + AS \fIquery\fR + [ WITH [ CASCADED | LOCAL ] CHECK OPTION ] +.fi +.SH "DESCRIPTION" +.PP +\fBCREATE VIEW\fR +defines a view of a query\&. The view is not physically materialized\&. Instead, the query is run every time the view is referenced in a query\&. +.PP +\fBCREATE OR REPLACE VIEW\fR +is similar, but if a view of the same name already exists, it is replaced\&. The new query must generate the same columns that were generated by the existing view query (that is, the same column names in the same order and with the same data types), but it may add additional columns to the end of the list\&. The calculations giving rise to the output columns may be completely different\&. +.PP +If a schema name is given (for example, +CREATE VIEW myschema\&.myview \&.\&.\&.) then the view is created in the specified schema\&. Otherwise it is created in the current schema\&. Temporary views exist in a special schema, so a schema name cannot be given when creating a temporary view\&. The name of the view must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema\&. +.SH "PARAMETERS" +.PP +TEMPORARY or TEMP +.RS 4 +If specified, the view is created as a temporary view\&. Temporary views are automatically dropped at the end of the current session\&. Existing permanent relations with the same name are not visible to the current session while the temporary view exists, unless they are referenced with schema\-qualified names\&. +.sp +If any of the tables referenced by the view are temporary, the view is created as a temporary view (whether +TEMPORARY +is specified or not)\&. +.RE +.PP +RECURSIVE +.RS 4 +Creates a recursive view\&. The syntax +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE RECURSIVE VIEW [ \fIschema\fR \&. ] \fIview_name\fR (\fIcolumn_names\fR) AS SELECT \fI\&.\&.\&.\fR; +.fi +.if n \{\ +.RE +.\} +.sp +is equivalent to +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW [ \fIschema\fR \&. ] \fIview_name\fR AS WITH RECURSIVE \fIview_name\fR (\fIcolumn_names\fR) AS (SELECT \fI\&.\&.\&.\fR) SELECT \fIcolumn_names\fR FROM \fIview_name\fR; +.fi +.if n \{\ +.RE +.\} +.sp +A view column name list must be specified for a recursive view\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of a view to be created\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +An optional list of names to be used for columns of the view\&. If not given, the column names are deduced from the query\&. +.RE +.PP +WITH ( \fIview_option_name\fR [= \fIview_option_value\fR] [, \&.\&.\&. ] ) +.RS 4 +This clause specifies optional parameters for a view; the following parameters are supported: +.PP +check_option (enum) +.RS 4 +This parameter may be either +local +or +cascaded, and is equivalent to specifying +WITH [ CASCADED | LOCAL ] CHECK OPTION +(see below)\&. +.RE +.PP +security_barrier (boolean) +.RS 4 +This should be used if the view is intended to provide row\-level security\&. See +Section\ \&41.5 +for full details\&. +.RE +.PP +security_invoker (boolean) +.RS 4 +This option causes the underlying base relations to be checked against the privileges of the user of the view rather than the view owner\&. See the notes below for full details\&. +.RE +.sp +All of the above options can be changed on existing views using +\fBALTER VIEW\fR\&. +.RE +.PP +\fIquery\fR +.RS 4 +A +\fBSELECT\fR +or +\fBVALUES\fR +command which will provide the columns and rows of the view\&. +.RE +.PP +WITH [ CASCADED | LOCAL ] CHECK OPTION +.RS 4 +This option controls the behavior of automatically updatable views\&. When this option is specified, +\fBINSERT\fR +and +\fBUPDATE\fR +commands on the view will be checked to ensure that new rows satisfy the view\-defining condition (that is, the new rows are checked to ensure that they are visible through the view)\&. If they are not, the update will be rejected\&. If the +CHECK OPTION +is not specified, +\fBINSERT\fR +and +\fBUPDATE\fR +commands on the view are allowed to create rows that are not visible through the view\&. The following check options are supported: +.PP +LOCAL +.RS 4 +New rows are only checked against the conditions defined directly in the view itself\&. Any conditions defined on underlying base views are not checked (unless they also specify the +CHECK OPTION)\&. +.RE +.PP +CASCADED +.RS 4 +New rows are checked against the conditions of the view and all underlying base views\&. If the +CHECK OPTION +is specified, and neither +LOCAL +nor +CASCADED +is specified, then +CASCADED +is assumed\&. +.RE +.sp +The +CHECK OPTION +may not be used with +RECURSIVE +views\&. +.sp +Note that the +CHECK OPTION +is only supported on views that are automatically updatable, and do not have +INSTEAD OF +triggers or +INSTEAD +rules\&. If an automatically updatable view is defined on top of a base view that has +INSTEAD OF +triggers, then the +LOCAL CHECK OPTION +may be used to check the conditions on the automatically updatable view, but the conditions on the base view with +INSTEAD OF +triggers will not be checked (a cascaded check option will not cascade down to a trigger\-updatable view, and any check options defined directly on a trigger\-updatable view will be ignored)\&. If the view or any of its base relations has an +INSTEAD +rule that causes the +\fBINSERT\fR +or +\fBUPDATE\fR +command to be rewritten, then all check options will be ignored in the rewritten query, including any checks from automatically updatable views defined on top of the relation with the +INSTEAD +rule\&. +.RE +.SH "NOTES" +.PP +Use the +\fBDROP VIEW\fR +statement to drop views\&. +.PP +Be careful that the names and types of the view\*(Aqs columns will be assigned the way you want\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW vista AS SELECT \*(AqHello World\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +is bad form because the column name defaults to +?column?; also, the column data type defaults to +text, which might not be what you wanted\&. Better style for a string literal in a view\*(Aqs result is something like: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW vista AS SELECT text \*(AqHello World\*(Aq AS hello; +.fi +.if n \{\ +.RE +.\} +.PP +By default, access to the underlying base relations referenced in the view is determined by the permissions of the view owner\&. In some cases, this can be used to provide secure but restricted access to the underlying tables\&. However, not all views are secure against tampering; see +Section\ \&41.5 +for details\&. +.PP +If the view has the +security_invoker +property set to +true, access to the underlying base relations is determined by the permissions of the user executing the query, rather than the view owner\&. Thus, the user of a security invoker view must have the relevant permissions on the view and its underlying base relations\&. +.PP +If any of the underlying base relations is a security invoker view, it will be treated as if it had been accessed directly from the original query\&. Thus, a security invoker view will always check its underlying base relations using the permissions of the current user, even if it is accessed from a view without the +security_invoker +property\&. +.PP +If any of the underlying base relations has +row\-level security +enabled, then by default, the row\-level security policies of the view owner are applied, and access to any additional relations referred to by those policies is determined by the permissions of the view owner\&. However, if the view has +security_invoker +set to +true, then the policies and permissions of the invoking user are used instead, as if the base relations had been referenced directly from the query using the view\&. +.PP +Functions called in the view are treated the same as if they had been called directly from the query using the view\&. Therefore, the user of a view must have permissions to call all functions used by the view\&. Functions in the view are executed with the privileges of the user executing the query or the function owner, depending on whether the functions are defined as +SECURITY INVOKER +or +SECURITY DEFINER\&. Thus, for example, calling +CURRENT_USER +directly in a view will always return the invoking user, not the view owner\&. This is not affected by the view\*(Aqs +security_invoker +setting, and so a view with +security_invoker +set to +false +is +\fInot\fR +equivalent to a +SECURITY DEFINER +function and those concepts should not be confused\&. +.PP +The user creating or replacing a view must have +USAGE +privileges on any schemas referred to in the view query, in order to look up the referenced objects in those schemas\&. Note, however, that this lookup only happens when the view is created or replaced\&. Therefore, the user of the view only requires the +USAGE +privilege on the schema containing the view, not on the schemas referred to in the view query, even for a security invoker view\&. +.PP +When +\fBCREATE OR REPLACE VIEW\fR +is used on an existing view, only the view\*(Aqs defining SELECT rule, plus any +WITH ( \&.\&.\&. ) +parameters and its +CHECK OPTION +are changed\&. Other view properties, including ownership, permissions, and non\-SELECT rules, remain unchanged\&. You must own the view to replace it (this includes being a member of the owning role)\&. +.SS "Updatable Views" +.PP +Simple views are automatically updatable: the system will allow +\fBINSERT\fR, +\fBUPDATE\fR +and +\fBDELETE\fR +statements to be used on the view in the same way as on a regular table\&. A view is automatically updatable if it satisfies all of the following conditions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The view must have exactly one entry in its +FROM +list, which must be a table or another updatable view\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The view definition must not contain +WITH, +DISTINCT, +GROUP BY, +HAVING, +LIMIT, or +OFFSET +clauses at the top level\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The view definition must not contain set operations (UNION, +INTERSECT +or +EXCEPT) at the top level\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The view\*(Aqs select list must not contain any aggregates, window functions or set\-returning functions\&. +.RE +.PP +An automatically updatable view may contain a mix of updatable and non\-updatable columns\&. A column is updatable if it is a simple reference to an updatable column of the underlying base relation; otherwise the column is read\-only, and an error will be raised if an +\fBINSERT\fR +or +\fBUPDATE\fR +statement attempts to assign a value to it\&. +.PP +If the view is automatically updatable the system will convert any +\fBINSERT\fR, +\fBUPDATE\fR +or +\fBDELETE\fR +statement on the view into the corresponding statement on the underlying base relation\&. +\fBINSERT\fR +statements that have an +ON CONFLICT UPDATE +clause are fully supported\&. +.PP +If an automatically updatable view contains a +WHERE +condition, the condition restricts which rows of the base relation are available to be modified by +\fBUPDATE\fR +and +\fBDELETE\fR +statements on the view\&. However, an +\fBUPDATE\fR +is allowed to change a row so that it no longer satisfies the +WHERE +condition, and thus is no longer visible through the view\&. Similarly, an +\fBINSERT\fR +command can potentially insert base\-relation rows that do not satisfy the +WHERE +condition and thus are not visible through the view (ON CONFLICT UPDATE +may similarly affect an existing row not visible through the view)\&. The +CHECK OPTION +may be used to prevent +\fBINSERT\fR +and +\fBUPDATE\fR +commands from creating such rows that are not visible through the view\&. +.PP +If an automatically updatable view is marked with the +security_barrier +property then all the view\*(Aqs +WHERE +conditions (and any conditions using operators which are marked as +LEAKPROOF) will always be evaluated before any conditions that a user of the view has added\&. See +Section\ \&41.5 +for full details\&. Note that, due to this, rows which are not ultimately returned (because they do not pass the user\*(Aqs +WHERE +conditions) may still end up being locked\&. +\fBEXPLAIN\fR +can be used to see which conditions are applied at the relation level (and therefore do not lock rows) and which are not\&. +.PP +A more complex view that does not satisfy all these conditions is read\-only by default: the system will not allow an insert, update, or delete on the view\&. You can get the effect of an updatable view by creating +INSTEAD OF +triggers on the view, which must convert attempted inserts, etc\&. on the view into appropriate actions on other tables\&. For more information see +CREATE TRIGGER (\fBCREATE_TRIGGER\fR(7))\&. Another possibility is to create rules (see +CREATE RULE (\fBCREATE_RULE\fR(7))), but in practice triggers are easier to understand and use correctly\&. +.PP +Note that the user performing the insert, update or delete on the view must have the corresponding insert, update or delete privilege on the view\&. In addition, by default, the view\*(Aqs owner must have the relevant privileges on the underlying base relations, whereas the user performing the update does not need any permissions on the underlying base relations (see +Section\ \&41.5)\&. However, if the view has +security_invoker +set to +true, the user performing the update, rather than the view owner, must have the relevant privileges on the underlying base relations\&. +.SH "EXAMPLES" +.PP +Create a view consisting of all comedy films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW comedies AS + SELECT * + FROM films + WHERE kind = \*(AqComedy\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +This will create a view containing the columns that are in the +film +table at the time of view creation\&. Though +* +was used to create the view, columns added later to the table will not be part of the view\&. +.PP +Create a view with +LOCAL CHECK OPTION: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW universal_comedies AS + SELECT * + FROM comedies + WHERE classification = \*(AqU\*(Aq + WITH LOCAL CHECK OPTION; +.fi +.if n \{\ +.RE +.\} +.sp +This will create a view based on the +comedies +view, showing only films with +kind = \*(AqComedy\*(Aq +and +classification = \*(AqU\*(Aq\&. Any attempt to +\fBINSERT\fR +or +\fBUPDATE\fR +a row in the view will be rejected if the new row doesn\*(Aqt have +classification = \*(AqU\*(Aq, but the film +kind +will not be checked\&. +.PP +Create a view with +CASCADED CHECK OPTION: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW pg_comedies AS + SELECT * + FROM comedies + WHERE classification = \*(AqPG\*(Aq + WITH CASCADED CHECK OPTION; +.fi +.if n \{\ +.RE +.\} +.sp +This will create a view that checks both the +kind +and +classification +of new rows\&. +.PP +Create a view with a mix of updatable and non\-updatable columns: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE VIEW comedies AS + SELECT f\&.*, + country_code_to_name(f\&.country_code) AS country, + (SELECT avg(r\&.rating) + FROM user_ratings r + WHERE r\&.film_id = f\&.id) AS avg_rating + FROM films f + WHERE f\&.kind = \*(AqComedy\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +This view will support +\fBINSERT\fR, +\fBUPDATE\fR +and +\fBDELETE\fR\&. All the columns from the +films +table will be updatable, whereas the computed columns +country +and +avg_rating +will be read\-only\&. +.PP +Create a recursive view consisting of the numbers from 1 to 100: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE RECURSIVE VIEW public\&.nums_1_100 (n) AS + VALUES (1) +UNION ALL + SELECT n+1 FROM nums_1_100 WHERE n < 100; +.fi +.if n \{\ +.RE +.\} +.sp +Notice that although the recursive view\*(Aqs name is schema\-qualified in this +\fBCREATE\fR, its internal self\-reference is not schema\-qualified\&. This is because the implicitly\-created CTE\*(Aqs name cannot be schema\-qualified\&. +.SH "COMPATIBILITY" +.PP +\fBCREATE OR REPLACE VIEW\fR +is a +PostgreSQL +language extension\&. So is the concept of a temporary view\&. The +WITH ( \&.\&.\&. ) +clause is an extension as well, as are security barrier views and security invoker views\&. +.SH "SEE ALSO" +ALTER VIEW (\fBALTER_VIEW\fR(7)), DROP VIEW (\fBDROP_VIEW\fR(7)), CREATE MATERIALIZED VIEW (\fBCREATE_MATERIALIZED_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/DEALLOCATE.7 b/doc/src/sgml/man7/DEALLOCATE.7 new file mode 100644 index 0000000..b383c31 --- /dev/null +++ b/doc/src/sgml/man7/DEALLOCATE.7 @@ -0,0 +1,66 @@ +'\" t +.\" Title: DEALLOCATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DEALLOCATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DEALLOCATE \- deallocate a prepared statement +.SH "SYNOPSIS" +.sp +.nf +DEALLOCATE [ PREPARE ] { \fIname\fR | ALL } +.fi +.SH "DESCRIPTION" +.PP +\fBDEALLOCATE\fR +is used to deallocate a previously prepared SQL statement\&. If you do not explicitly deallocate a prepared statement, it is deallocated when the session ends\&. +.PP +For more information on prepared statements, see +\fBPREPARE\fR(7)\&. +.SH "PARAMETERS" +.PP +PREPARE +.RS 4 +This key word is ignored\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the prepared statement to deallocate\&. +.RE +.PP +ALL +.RS 4 +Deallocate all prepared statements\&. +.RE +.SH "COMPATIBILITY" +.PP +The SQL standard includes a +\fBDEALLOCATE\fR +statement, but it is only for use in embedded SQL\&. +.SH "SEE ALSO" +\fBEXECUTE\fR(7), \fBPREPARE\fR(7) diff --git a/doc/src/sgml/man7/DECLARE.7 b/doc/src/sgml/man7/DECLARE.7 new file mode 100644 index 0000000..f5b13f9 --- /dev/null +++ b/doc/src/sgml/man7/DECLARE.7 @@ -0,0 +1,345 @@ +'\" t +.\" Title: DECLARE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DECLARE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DECLARE \- define a cursor +.SH "SYNOPSIS" +.sp +.nf +DECLARE \fIname\fR [ BINARY ] [ ASENSITIVE | INSENSITIVE ] [ [ NO ] SCROLL ] + CURSOR [ { WITH | WITHOUT } HOLD ] FOR \fIquery\fR +.fi +.SH "DESCRIPTION" +.PP +\fBDECLARE\fR +allows a user to create cursors, which can be used to retrieve a small number of rows at a time out of a larger query\&. After the cursor is created, rows are fetched from it using +\fBFETCH\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +This page describes usage of cursors at the SQL command level\&. If you are trying to use cursors inside a +PL/pgSQL +function, the rules are different \(em see +Section\ \&43.7\&. +.sp .5v +.RE +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the cursor to be created\&. +.RE +.PP +BINARY +.RS 4 +Causes the cursor to return data in binary rather than in text format\&. +.RE +.PP +ASENSITIVE +.br +INSENSITIVE +.RS 4 +Cursor sensitivity determines whether changes to the data underlying the cursor, done in the same transaction, after the cursor has been declared, are visible in the cursor\&. +INSENSITIVE +means they are not visible, +ASENSITIVE +means the behavior is implementation\-dependent\&. A third behavior, +SENSITIVE, meaning that such changes are visible in the cursor, is not available in +PostgreSQL\&. In +PostgreSQL, all cursors are insensitive; so these key words have no effect and are only accepted for compatibility with the SQL standard\&. +.sp +Specifying +INSENSITIVE +together with +FOR UPDATE +or +FOR SHARE +is an error\&. +.RE +.PP +SCROLL +.br +NO SCROLL +.RS 4 +SCROLL +specifies that the cursor can be used to retrieve rows in a nonsequential fashion (e\&.g\&., backward)\&. Depending upon the complexity of the query\*(Aqs execution plan, specifying +SCROLL +might impose a performance penalty on the query\*(Aqs execution time\&. +NO SCROLL +specifies that the cursor cannot be used to retrieve rows in a nonsequential fashion\&. The default is to allow scrolling in some cases; this is not the same as specifying +SCROLL\&. See +Notes +below for details\&. +.RE +.PP +WITH HOLD +.br +WITHOUT HOLD +.RS 4 +WITH HOLD +specifies that the cursor can continue to be used after the transaction that created it successfully commits\&. +WITHOUT HOLD +specifies that the cursor cannot be used outside of the transaction that created it\&. If neither +WITHOUT HOLD +nor +WITH HOLD +is specified, +WITHOUT HOLD +is the default\&. +.RE +.PP +\fIquery\fR +.RS 4 +A +\fBSELECT\fR +or +\fBVALUES\fR +command which will provide the rows to be returned by the cursor\&. +.RE +.PP +The key words +ASENSITIVE, +BINARY, +INSENSITIVE, and +SCROLL +can appear in any order\&. +.SH "NOTES" +.PP +Normal cursors return data in text format, the same as a +\fBSELECT\fR +would produce\&. The +BINARY +option specifies that the cursor should return data in binary format\&. This reduces conversion effort for both the server and client, at the cost of more programmer effort to deal with platform\-dependent binary data formats\&. As an example, if a query returns a value of one from an integer column, you would get a string of +1 +with a default cursor, whereas with a binary cursor you would get a 4\-byte field containing the internal representation of the value (in big\-endian byte order)\&. +.PP +Binary cursors should be used carefully\&. Many applications, including +psql, are not prepared to handle binary cursors and expect data to come back in the text format\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +When the client application uses the +\(lqextended query\(rq +protocol to issue a +\fBFETCH\fR +command, the Bind protocol message specifies whether data is to be retrieved in text or binary format\&. This choice overrides the way that the cursor is defined\&. The concept of a binary cursor as such is thus obsolete when using extended query protocol \(em any cursor can be treated as either text or binary\&. +.sp .5v +.RE +.PP +Unless +WITH HOLD +is specified, the cursor created by this command can only be used within the current transaction\&. Thus, +\fBDECLARE\fR +without +WITH HOLD +is useless outside a transaction block: the cursor would survive only to the completion of the statement\&. Therefore +PostgreSQL +reports an error if such a command is used outside a transaction block\&. Use +\fBBEGIN\fR +and +\fBCOMMIT\fR +(or +\fBROLLBACK\fR) to define a transaction block\&. +.PP +If +WITH HOLD +is specified and the transaction that created the cursor successfully commits, the cursor can continue to be accessed by subsequent transactions in the same session\&. (But if the creating transaction is aborted, the cursor is removed\&.) A cursor created with +WITH HOLD +is closed when an explicit +\fBCLOSE\fR +command is issued on it, or the session ends\&. In the current implementation, the rows represented by a held cursor are copied into a temporary file or memory area so that they remain available for subsequent transactions\&. +.PP +WITH HOLD +may not be specified when the query includes +FOR UPDATE +or +FOR SHARE\&. +.PP +The +SCROLL +option should be specified when defining a cursor that will be used to fetch backwards\&. This is required by the SQL standard\&. However, for compatibility with earlier versions, +PostgreSQL +will allow backward fetches without +SCROLL, if the cursor\*(Aqs query plan is simple enough that no extra overhead is needed to support it\&. However, application developers are advised not to rely on using backward fetches from a cursor that has not been created with +SCROLL\&. If +NO SCROLL +is specified, then backward fetches are disallowed in any case\&. +.PP +Backward fetches are also disallowed when the query includes +FOR UPDATE +or +FOR SHARE; therefore +SCROLL +may not be specified in this case\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +Scrollable cursors may give unexpected results if they invoke any volatile functions (see +Section\ \&38.7)\&. When a previously fetched row is re\-fetched, the functions might be re\-executed, perhaps leading to results different from the first time\&. It\*(Aqs best to specify +NO SCROLL +for a query involving volatile functions\&. If that is not practical, one workaround is to declare the cursor +SCROLL WITH HOLD +and commit the transaction before reading any rows from it\&. This will force the entire output of the cursor to be materialized in temporary storage, so that volatile functions are executed exactly once for each row\&. +.sp .5v +.RE +.PP +If the cursor\*(Aqs query includes +FOR UPDATE +or +FOR SHARE, then returned rows are locked at the time they are first fetched, in the same way as for a regular +\fBSELECT\fR +command with these options\&. In addition, the returned rows will be the most up\-to\-date versions\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +It is generally recommended to use +FOR UPDATE +if the cursor is intended to be used with +\fBUPDATE \&.\&.\&. WHERE CURRENT OF\fR +or +\fBDELETE \&.\&.\&. WHERE CURRENT OF\fR\&. Using +FOR UPDATE +prevents other sessions from changing the rows between the time they are fetched and the time they are updated\&. Without +FOR UPDATE, a subsequent +WHERE CURRENT OF +command will have no effect if the row was changed since the cursor was created\&. +.PP +Another reason to use +FOR UPDATE +is that without it, a subsequent +WHERE CURRENT OF +might fail if the cursor query does not meet the SQL standard\*(Aqs rules for being +\(lqsimply updatable\(rq +(in particular, the cursor must reference just one table and not use grouping or +ORDER BY)\&. Cursors that are not simply updatable might work, or might not, depending on plan choice details; so in the worst case, an application might work in testing and then fail in production\&. If +FOR UPDATE +is specified, the cursor is guaranteed to be updatable\&. +.PP +The main reason not to use +FOR UPDATE +with +WHERE CURRENT OF +is if you need the cursor to be scrollable, or to be isolated from concurrent updates (that is, continue to show the old data)\&. If this is a requirement, pay close heed to the caveats shown above\&. +.sp .5v +.RE +.PP +The SQL standard only makes provisions for cursors in embedded +SQL\&. The +PostgreSQL +server does not implement an +\fBOPEN\fR +statement for cursors; a cursor is considered to be open when it is declared\&. However, +ECPG, the embedded SQL preprocessor for +PostgreSQL, supports the standard SQL cursor conventions, including those involving +\fBDECLARE\fR +and +\fBOPEN\fR +statements\&. +.PP +You can see all available cursors by querying the +pg_cursors +system view\&. +.SH "EXAMPLES" +.PP +To declare a cursor: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DECLARE liahona CURSOR FOR SELECT * FROM films; +.fi +.if n \{\ +.RE +.\} +.sp +See +\fBFETCH\fR(7) +for more examples of cursor usage\&. +.SH "COMPATIBILITY" +.PP +The SQL standard allows cursors only in embedded +SQL +and in modules\&. +PostgreSQL +permits cursors to be used interactively\&. +.PP +According to the SQL standard, changes made to insensitive cursors by +UPDATE \&.\&.\&. WHERE CURRENT OF +and +DELETE \&.\&.\&. WHERE CURRENT OF +statements are visible in that same cursor\&. +PostgreSQL +treats these statements like all other data changing statements in that they are not visible in insensitive cursors\&. +.PP +Binary cursors are a +PostgreSQL +extension\&. +.SH "SEE ALSO" +\fBCLOSE\fR(7), \fBFETCH\fR(7), \fBMOVE\fR(7) diff --git a/doc/src/sgml/man7/DELETE.7 b/doc/src/sgml/man7/DELETE.7 new file mode 100644 index 0000000..93676b8 --- /dev/null +++ b/doc/src/sgml/man7/DELETE.7 @@ -0,0 +1,320 @@ +'\" t +.\" Title: DELETE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DELETE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DELETE \- delete rows of a table +.SH "SYNOPSIS" +.sp +.nf +[ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ] +DELETE FROM [ ONLY ] \fItable_name\fR [ * ] [ [ AS ] \fIalias\fR ] + [ USING \fIfrom_item\fR [, \&.\&.\&.] ] + [ WHERE \fIcondition\fR | WHERE CURRENT OF \fIcursor_name\fR ] + [ RETURNING * | \fIoutput_expression\fR [ [ AS ] \fIoutput_name\fR ] [, \&.\&.\&.] ] +.fi +.SH "DESCRIPTION" +.PP +\fBDELETE\fR +deletes rows that satisfy the +WHERE +clause from the specified table\&. If the +WHERE +clause is absent, the effect is to delete all rows in the table\&. The result is a valid, but empty table\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +.PP +\fBTRUNCATE\fR +provides a faster mechanism to remove all rows from a table\&. +.sp .5v +.RE +.PP +There are two ways to delete rows in a table using information contained in other tables in the database: using sub\-selects, or specifying additional tables in the +USING +clause\&. Which technique is more appropriate depends on the specific circumstances\&. +.PP +The optional +RETURNING +clause causes +\fBDELETE\fR +to compute and return value(s) based on each row actually deleted\&. Any expression using the table\*(Aqs columns, and/or columns of other tables mentioned in +USING, can be computed\&. The syntax of the +RETURNING +list is identical to that of the output list of +\fBSELECT\fR\&. +.PP +You must have the +DELETE +privilege on the table to delete from it, as well as the +SELECT +privilege for any table in the +USING +clause or whose values are read in the +\fIcondition\fR\&. +.SH "PARAMETERS" +.PP +\fIwith_query\fR +.RS 4 +The +WITH +clause allows you to specify one or more subqueries that can be referenced by name in the +\fBDELETE\fR +query\&. See +Section\ \&7.8 +and +\fBSELECT\fR(7) +for details\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table to delete rows from\&. If +ONLY +is specified before the table name, matching rows are deleted from the named table only\&. If +ONLY +is not specified, matching rows are also deleted from any tables inheriting from the named table\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +\fIalias\fR +.RS 4 +A substitute name for the target table\&. When an alias is provided, it completely hides the actual name of the table\&. For example, given +DELETE FROM foo AS f, the remainder of the +\fBDELETE\fR +statement must refer to this table as +f +not +foo\&. +.RE +.PP +\fIfrom_item\fR +.RS 4 +A table expression allowing columns from other tables to appear in the +WHERE +condition\&. This uses the same syntax as the +FROM +clause of a +\fBSELECT\fR +statement; for example, an alias for the table name can be specified\&. Do not repeat the target table as a +\fIfrom_item\fR +unless you wish to set up a self\-join (in which case it must appear with an alias in the +\fIfrom_item\fR)\&. +.RE +.PP +\fIcondition\fR +.RS 4 +An expression that returns a value of type +boolean\&. Only rows for which this expression returns +true +will be deleted\&. +.RE +.PP +\fIcursor_name\fR +.RS 4 +The name of the cursor to use in a +WHERE CURRENT OF +condition\&. The row to be deleted is the one most recently fetched from this cursor\&. The cursor must be a non\-grouping query on the +\fBDELETE\fR\*(Aqs target table\&. Note that +WHERE CURRENT OF +cannot be specified together with a Boolean condition\&. See +\fBDECLARE\fR(7) +for more information about using cursors with +WHERE CURRENT OF\&. +.RE +.PP +\fIoutput_expression\fR +.RS 4 +An expression to be computed and returned by the +\fBDELETE\fR +command after each row is deleted\&. The expression can use any column names of the table named by +\fItable_name\fR +or table(s) listed in +USING\&. Write +* +to return all columns\&. +.RE +.PP +\fIoutput_name\fR +.RS 4 +A name to use for a returned column\&. +.RE +.SH "OUTPUTS" +.PP +On successful completion, a +\fBDELETE\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE \fIcount\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fIcount\fR +is the number of rows deleted\&. Note that the number may be less than the number of rows that matched the +\fIcondition\fR +when deletes were suppressed by a +BEFORE DELETE +trigger\&. If +\fIcount\fR +is 0, no rows were deleted by the query (this is not considered an error)\&. +.PP +If the +\fBDELETE\fR +command contains a +RETURNING +clause, the result will be similar to that of a +\fBSELECT\fR +statement containing the columns and values defined in the +RETURNING +list, computed over the row(s) deleted by the command\&. +.SH "NOTES" +.PP +PostgreSQL +lets you reference columns of other tables in the +WHERE +condition by specifying the other tables in the +USING +clause\&. For example, to delete all films produced by a given producer, one can do: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE FROM films USING producers + WHERE producer_id = producers\&.id AND producers\&.name = \*(Aqfoo\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +What is essentially happening here is a join between +films +and +producers, with all successfully joined +films +rows being marked for deletion\&. This syntax is not standard\&. A more standard way to do it is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE FROM films + WHERE producer_id IN (SELECT id FROM producers WHERE name = \*(Aqfoo\*(Aq); +.fi +.if n \{\ +.RE +.\} +.sp +In some cases the join style is easier to write or faster to execute than the sub\-select style\&. +.SH "EXAMPLES" +.PP +Delete all films but musicals: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE FROM films WHERE kind <> \*(AqMusical\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Clear the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE FROM films; +.fi +.if n \{\ +.RE +.\} +.PP +Delete completed tasks, returning full details of the deleted rows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE FROM tasks WHERE status = \*(AqDONE\*(Aq RETURNING *; +.fi +.if n \{\ +.RE +.\} +.PP +Delete the row of +tasks +on which the cursor +c_tasks +is currently positioned: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DELETE FROM tasks WHERE CURRENT OF c_tasks; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to the +SQL +standard, except that the +USING +and +RETURNING +clauses are +PostgreSQL +extensions, as is the ability to use +WITH +with +\fBDELETE\fR\&. +.SH "SEE ALSO" +\fBTRUNCATE\fR(7) diff --git a/doc/src/sgml/man7/DISCARD.7 b/doc/src/sgml/man7/DISCARD.7 new file mode 100644 index 0000000..1a80482 --- /dev/null +++ b/doc/src/sgml/man7/DISCARD.7 @@ -0,0 +1,96 @@ +'\" t +.\" Title: DISCARD +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DISCARD" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DISCARD \- discard session state +.SH "SYNOPSIS" +.sp +.nf +DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP } +.fi +.SH "DESCRIPTION" +.PP +\fBDISCARD\fR +releases internal resources associated with a database session\&. This command is useful for partially or fully resetting the session\*(Aqs state\&. There are several subcommands to release different types of resources; the +\fBDISCARD ALL\fR +variant subsumes all the others, and also resets additional state\&. +.SH "PARAMETERS" +.PP +PLANS +.RS 4 +Releases all cached query plans, forcing re\-planning to occur the next time the associated prepared statement is used\&. +.RE +.PP +SEQUENCES +.RS 4 +Discards all cached sequence\-related state, including +\fBcurrval()\fR/\fBlastval()\fR +information and any preallocated sequence values that have not yet been returned by +\fBnextval()\fR\&. (See +CREATE SEQUENCE (\fBCREATE_SEQUENCE\fR(7)) +for a description of preallocated sequence values\&.) +.RE +.PP +TEMPORARY or TEMP +.RS 4 +Drops all temporary tables created in the current session\&. +.RE +.PP +ALL +.RS 4 +Releases all temporary resources associated with the current session and resets the session to its initial state\&. Currently, this has the same effect as executing the following sequence of statements: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CLOSE ALL; +SET SESSION AUTHORIZATION DEFAULT; +RESET ALL; +DEALLOCATE ALL; +UNLISTEN *; +SELECT pg_advisory_unlock_all(); +DISCARD PLANS; +DISCARD TEMP; +DISCARD SEQUENCES; +.fi +.if n \{\ +.RE +.\} +.RE +.SH "NOTES" +.PP +\fBDISCARD ALL\fR +cannot be executed inside a transaction block\&. +.SH "COMPATIBILITY" +.PP +\fBDISCARD\fR +is a +PostgreSQL +extension\&. diff --git a/doc/src/sgml/man7/DO.7 b/doc/src/sgml/man7/DO.7 new file mode 100644 index 0000000..0bd4e2b --- /dev/null +++ b/doc/src/sgml/man7/DO.7 @@ -0,0 +1,106 @@ +'\" t +.\" Title: DO +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DO" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DO \- execute an anonymous code block +.SH "SYNOPSIS" +.sp +.nf +DO [ LANGUAGE \fIlang_name\fR ] \fIcode\fR +.fi +.SH "DESCRIPTION" +.PP +\fBDO\fR +executes an anonymous code block, or in other words a transient anonymous function in a procedural language\&. +.PP +The code block is treated as though it were the body of a function with no parameters, returning +void\&. It is parsed and executed a single time\&. +.PP +The optional +LANGUAGE +clause can be written either before or after the code block\&. +.SH "PARAMETERS" +.PP +\fIcode\fR +.RS 4 +The procedural language code to be executed\&. This must be specified as a string literal, just as in +\fBCREATE FUNCTION\fR\&. Use of a dollar\-quoted literal is recommended\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the procedural language the code is written in\&. If omitted, the default is +plpgsql\&. +.RE +.SH "NOTES" +.PP +The procedural language to be used must already have been installed into the current database by means of +\fBCREATE EXTENSION\fR\&. +plpgsql +is installed by default, but other languages are not\&. +.PP +The user must have +USAGE +privilege for the procedural language, or must be a superuser if the language is untrusted\&. This is the same privilege requirement as for creating a function in the language\&. +.PP +If +\fBDO\fR +is executed in a transaction block, then the procedure code cannot execute transaction control statements\&. Transaction control statements are only allowed if +\fBDO\fR +is executed in its own transaction\&. +.SH "EXAMPLES" +.PP +Grant all privileges on all views in schema +public +to role +webuser: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DO $$DECLARE r record; +BEGIN + FOR r IN SELECT table_schema, table_name FROM information_schema\&.tables + WHERE table_type = \*(AqVIEW\*(Aq AND table_schema = \*(Aqpublic\*(Aq + LOOP + EXECUTE \*(AqGRANT ALL ON \*(Aq || quote_ident(r\&.table_schema) || \*(Aq\&.\*(Aq || quote_ident(r\&.table_name) || \*(Aq TO webuser\*(Aq; + END LOOP; +END$$; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDO\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE LANGUAGE (\fBCREATE_LANGUAGE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_ACCESS_METHOD.7 b/doc/src/sgml/man7/DROP_ACCESS_METHOD.7 new file mode 100644 index 0000000..631a6ad --- /dev/null +++ b/doc/src/sgml/man7/DROP_ACCESS_METHOD.7 @@ -0,0 +1,84 @@ +'\" t +.\" Title: DROP ACCESS METHOD +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP ACCESS METHOD" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_ACCESS_METHOD \- remove an access method +.SH "SYNOPSIS" +.sp +.nf +DROP ACCESS METHOD [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP ACCESS METHOD\fR +removes an existing access method\&. Only superusers can drop access methods\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the access method does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of an existing access method\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the access method (such as operator classes, operator families, and indexes), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the access method if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Drop the access method +heptree: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP ACCESS METHOD heptree; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP ACCESS METHOD\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE ACCESS METHOD (\fBCREATE_ACCESS_METHOD\fR(7)) diff --git a/doc/src/sgml/man7/DROP_AGGREGATE.7 b/doc/src/sgml/man7/DROP_AGGREGATE.7 new file mode 100644 index 0000000..a3f8834 --- /dev/null +++ b/doc/src/sgml/man7/DROP_AGGREGATE.7 @@ -0,0 +1,145 @@ +'\" t +.\" Title: DROP AGGREGATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP AGGREGATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_AGGREGATE \- remove an aggregate function +.SH "SYNOPSIS" +.sp +.nf +DROP AGGREGATE [ IF EXISTS ] \fIname\fR ( \fIaggregate_signature\fR ) [, \&.\&.\&.] [ CASCADE | RESTRICT ] + +where \fIaggregate_signature\fR is: + +* | +[ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] | +[ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP AGGREGATE\fR +removes an existing aggregate function\&. To execute this command the current user must be the owner of the aggregate function\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the aggregate does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing aggregate function\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN +or +VARIADIC\&. If omitted, the default is +IN\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Note that +\fBDROP AGGREGATE\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the aggregate function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +An input data type on which the aggregate function operates\&. To reference a zero\-argument aggregate function, write +* +in place of the list of argument specifications\&. To reference an ordered\-set aggregate function, write +ORDER BY +between the direct and aggregated argument specifications\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the aggregate function (such as views using it), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the aggregate function if any objects depend on it\&. This is the default\&. +.RE +.SH "NOTES" +.PP +Alternative syntaxes for referencing ordered\-set aggregates are described under +ALTER AGGREGATE (\fBALTER_AGGREGATE\fR(7))\&. +.SH "EXAMPLES" +.PP +To remove the aggregate function +myavg +for type +integer: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP AGGREGATE myavg(integer); +.fi +.if n \{\ +.RE +.\} +.PP +To remove the hypothetical\-set aggregate function +myrank, which takes an arbitrary list of ordering columns and a matching list of direct arguments: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP AGGREGATE myrank(VARIADIC "any" ORDER BY VARIADIC "any"); +.fi +.if n \{\ +.RE +.\} +.PP +To remove multiple aggregate functions in one command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP AGGREGATE myavg(integer), myavg(bigint); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP AGGREGATE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER AGGREGATE (\fBALTER_AGGREGATE\fR(7)), CREATE AGGREGATE (\fBCREATE_AGGREGATE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_CAST.7 b/doc/src/sgml/man7/DROP_CAST.7 new file mode 100644 index 0000000..7a7985d --- /dev/null +++ b/doc/src/sgml/man7/DROP_CAST.7 @@ -0,0 +1,88 @@ +'\" t +.\" Title: DROP CAST +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP CAST" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_CAST \- remove a cast +.SH "SYNOPSIS" +.sp +.nf +DROP CAST [ IF EXISTS ] (\fIsource_type\fR AS \fItarget_type\fR) [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP CAST\fR +removes a previously defined cast\&. +.PP +To be able to drop a cast, you must own the source or the target data type\&. These are the same privileges that are required to create a cast\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the cast does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIsource_type\fR +.RS 4 +The name of the source data type of the cast\&. +.RE +.PP +\fItarget_type\fR +.RS 4 +The name of the target data type of the cast\&. +.RE +.PP +CASCADE +.br +RESTRICT +.RS 4 +These key words do not have any effect, since there are no dependencies on casts\&. +.RE +.SH "EXAMPLES" +.PP +To drop the cast from type +text +to type +int: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP CAST (text AS int); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBDROP CAST\fR +command conforms to the SQL standard\&. +.SH "SEE ALSO" +CREATE CAST (\fBCREATE_CAST\fR(7)) diff --git a/doc/src/sgml/man7/DROP_COLLATION.7 b/doc/src/sgml/man7/DROP_COLLATION.7 new file mode 100644 index 0000000..a6cf672 --- /dev/null +++ b/doc/src/sgml/man7/DROP_COLLATION.7 @@ -0,0 +1,89 @@ +'\" t +.\" Title: DROP COLLATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP COLLATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_COLLATION \- remove a collation +.SH "SYNOPSIS" +.sp +.nf +DROP COLLATION [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP COLLATION\fR +removes a previously defined collation\&. To be able to drop a collation, you must own the collation\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the collation does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the collation\&. The collation name can be schema\-qualified\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the collation, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the collation if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To drop the collation named +german: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP COLLATION german; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBDROP COLLATION\fR +command conforms to the +SQL +standard, apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER COLLATION (\fBALTER_COLLATION\fR(7)), CREATE COLLATION (\fBCREATE_COLLATION\fR(7)) diff --git a/doc/src/sgml/man7/DROP_CONVERSION.7 b/doc/src/sgml/man7/DROP_CONVERSION.7 new file mode 100644 index 0000000..5f5006e --- /dev/null +++ b/doc/src/sgml/man7/DROP_CONVERSION.7 @@ -0,0 +1,85 @@ +'\" t +.\" Title: DROP CONVERSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP CONVERSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_CONVERSION \- remove a conversion +.SH "SYNOPSIS" +.sp +.nf +DROP CONVERSION [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP CONVERSION\fR +removes a previously defined conversion\&. To be able to drop a conversion, you must own the conversion\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the conversion does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the conversion\&. The conversion name can be schema\-qualified\&. +.RE +.PP +CASCADE +.br +RESTRICT +.RS 4 +These key words do not have any effect, since there are no dependencies on conversions\&. +.RE +.SH "EXAMPLES" +.PP +To drop the conversion named +myname: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP CONVERSION myname; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP CONVERSION\fR +statement in the SQL standard, but a +\fBDROP TRANSLATION\fR +statement that goes along with the +\fBCREATE TRANSLATION\fR +statement that is similar to the +\fBCREATE CONVERSION\fR +statement in PostgreSQL\&. +.SH "SEE ALSO" +ALTER CONVERSION (\fBALTER_CONVERSION\fR(7)), CREATE CONVERSION (\fBCREATE_CONVERSION\fR(7)) diff --git a/doc/src/sgml/man7/DROP_DATABASE.7 b/doc/src/sgml/man7/DROP_DATABASE.7 new file mode 100644 index 0000000..87c805f --- /dev/null +++ b/doc/src/sgml/man7/DROP_DATABASE.7 @@ -0,0 +1,86 @@ +'\" t +.\" Title: DROP DATABASE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP DATABASE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_DATABASE \- remove a database +.SH "SYNOPSIS" +.sp +.nf +DROP DATABASE [ IF EXISTS ] \fIname\fR [ [ WITH ] ( \fIoption\fR [, \&.\&.\&.] ) ] + +where \fIoption\fR can be: + + FORCE +.fi +.SH "DESCRIPTION" +.PP +\fBDROP DATABASE\fR +drops a database\&. It removes the catalog entries for the database and deletes the directory containing the data\&. It can only be executed by the database owner\&. It cannot be executed while you are connected to the target database\&. (Connect to +postgres +or any other database to issue this command\&.) Also, if anyone else is connected to the target database, this command will fail unless you use the +FORCE +option described below\&. +.PP +\fBDROP DATABASE\fR +cannot be undone\&. Use it with care! +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the database does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the database to remove\&. +.RE +.PP +FORCE +.RS 4 +Attempt to terminate all existing connections to the target database\&. It doesn\*(Aqt terminate if prepared transactions, active logical replication slots or subscriptions are present in the target database\&. +.sp +This will fail if the current user has no permissions to terminate other connections\&. Required permissions are the same as with +pg_terminate_backend, described in +Section\ \&9.27.2\&. This will also fail if we are not able to terminate connections\&. +.RE +.SH "NOTES" +.PP +\fBDROP DATABASE\fR +cannot be executed inside a transaction block\&. +.PP +This command cannot be executed while connected to the target database\&. Thus, it might be more convenient to use the program +\fBdropdb\fR(1) +instead, which is a wrapper around this command\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP DATABASE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE DATABASE (\fBCREATE_DATABASE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_DOMAIN.7 b/doc/src/sgml/man7/DROP_DOMAIN.7 new file mode 100644 index 0000000..b2b0e14 --- /dev/null +++ b/doc/src/sgml/man7/DROP_DOMAIN.7 @@ -0,0 +1,85 @@ +'\" t +.\" Title: DROP DOMAIN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP DOMAIN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_DOMAIN \- remove a domain +.SH "SYNOPSIS" +.sp +.nf +DROP DOMAIN [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP DOMAIN\fR +removes a domain\&. Only the owner of a domain can remove it\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the domain does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing domain\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the domain (such as table columns), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the domain if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To remove the domain +box: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP DOMAIN box; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to the SQL standard, except for the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE DOMAIN (\fBCREATE_DOMAIN\fR(7)), ALTER DOMAIN (\fBALTER_DOMAIN\fR(7)) diff --git a/doc/src/sgml/man7/DROP_EVENT_TRIGGER.7 b/doc/src/sgml/man7/DROP_EVENT_TRIGGER.7 new file mode 100644 index 0000000..f9a6e1a --- /dev/null +++ b/doc/src/sgml/man7/DROP_EVENT_TRIGGER.7 @@ -0,0 +1,83 @@ +'\" t +.\" Title: DROP EVENT TRIGGER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP EVENT TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_EVENT_TRIGGER \- remove an event trigger +.SH "SYNOPSIS" +.sp +.nf +DROP EVENT TRIGGER [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP EVENT TRIGGER\fR +removes an existing event trigger\&. To execute this command, the current user must be the owner of the event trigger\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the event trigger does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the event trigger to remove\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the trigger, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the trigger if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Destroy the trigger +snitch: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP EVENT TRIGGER snitch; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP EVENT TRIGGER\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE EVENT TRIGGER (\fBCREATE_EVENT_TRIGGER\fR(7)), ALTER EVENT TRIGGER (\fBALTER_EVENT_TRIGGER\fR(7)) diff --git a/doc/src/sgml/man7/DROP_EXTENSION.7 b/doc/src/sgml/man7/DROP_EXTENSION.7 new file mode 100644 index 0000000..1921d74 --- /dev/null +++ b/doc/src/sgml/man7/DROP_EXTENSION.7 @@ -0,0 +1,98 @@ +'\" t +.\" Title: DROP EXTENSION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP EXTENSION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_EXTENSION \- remove an extension +.SH "SYNOPSIS" +.sp +.nf +DROP EXTENSION [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP EXTENSION\fR +removes extensions from the database\&. Dropping an extension causes its member objects, and other explicitly dependent routines (see +ALTER ROUTINE (\fBALTER_ROUTINE\fR(7)), the +DEPENDS ON EXTENSION \fIextension_name\fR +action), to be dropped as well\&. +.PP +You must own the extension to use +\fBDROP EXTENSION\fR\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the extension does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of an installed extension\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the extension, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +This option prevents the specified extensions from being dropped if other objects, besides these extensions, their members, and their explicitly dependent routines, depend on them\&.\ \& This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To remove the extension +hstore +from the current database: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP EXTENSION hstore; +.fi +.if n \{\ +.RE +.\} +.sp +This command will fail if any of +hstore\*(Aqs 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\&. +.SH "COMPATIBILITY" +.PP +\fBDROP EXTENSION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE EXTENSION (\fBCREATE_EXTENSION\fR(7)), ALTER EXTENSION (\fBALTER_EXTENSION\fR(7)) diff --git a/doc/src/sgml/man7/DROP_FOREIGN_DATA_WRAPPER.7 b/doc/src/sgml/man7/DROP_FOREIGN_DATA_WRAPPER.7 new file mode 100644 index 0000000..8bc2daf --- /dev/null +++ b/doc/src/sgml/man7/DROP_FOREIGN_DATA_WRAPPER.7 @@ -0,0 +1,86 @@ +'\" t +.\" Title: DROP FOREIGN DATA WRAPPER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP FOREIGN DATA WRAPPER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_FOREIGN_DATA_WRAPPER \- remove a foreign\-data wrapper +.SH "SYNOPSIS" +.sp +.nf +DROP FOREIGN DATA WRAPPER [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP FOREIGN DATA WRAPPER\fR +removes an existing foreign\-data wrapper\&. To execute this command, the current user must be the owner of the foreign\-data wrapper\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the foreign\-data wrapper does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of an existing foreign\-data wrapper\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the foreign\-data wrapper (such as foreign tables and servers), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the foreign\-data wrapper if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Drop the foreign\-data wrapper +dbi: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP FOREIGN DATA WRAPPER dbi; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP FOREIGN DATA WRAPPER\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. The +IF EXISTS +clause is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE FOREIGN DATA WRAPPER (\fBCREATE_FOREIGN_DATA_WRAPPER\fR(7)), ALTER FOREIGN DATA WRAPPER (\fBALTER_FOREIGN_DATA_WRAPPER\fR(7)) diff --git a/doc/src/sgml/man7/DROP_FOREIGN_TABLE.7 b/doc/src/sgml/man7/DROP_FOREIGN_TABLE.7 new file mode 100644 index 0000000..80aba65 --- /dev/null +++ b/doc/src/sgml/man7/DROP_FOREIGN_TABLE.7 @@ -0,0 +1,87 @@ +'\" t +.\" Title: DROP FOREIGN TABLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP FOREIGN TABLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_FOREIGN_TABLE \- remove a foreign table +.SH "SYNOPSIS" +.sp +.nf +DROP FOREIGN TABLE [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP FOREIGN TABLE\fR +removes a foreign table\&. Only the owner of a foreign table can remove it\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the foreign table does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the foreign table to drop\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the foreign table (such as views), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the foreign table if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To destroy two foreign tables, +films +and +distributors: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP FOREIGN TABLE films, distributors; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to ISO/IEC 9075\-9 (SQL/MED), except that the standard only allows one foreign table to be dropped per command, and apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER FOREIGN TABLE (\fBALTER_FOREIGN_TABLE\fR(7)), CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_FUNCTION.7 b/doc/src/sgml/man7/DROP_FUNCTION.7 new file mode 100644 index 0000000..f026467 --- /dev/null +++ b/doc/src/sgml/man7/DROP_FUNCTION.7 @@ -0,0 +1,186 @@ +'\" t +.\" Title: DROP FUNCTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP FUNCTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_FUNCTION \- remove a function +.SH "SYNOPSIS" +.sp +.nf +DROP FUNCTION [ IF EXISTS ] \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] [, \&.\&.\&.] + [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP FUNCTION\fR +removes the definition of an existing function\&. To execute this command the user must be the owner of the function\&. The argument types to the function must be specified, since several different functions can exist with the same name and different argument lists\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the function does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing function\&. If no argument list is specified, the name must be unique in its schema\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. Note that +\fBDROP FUNCTION\fR +does not actually pay any attention to +OUT +arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the +IN, +INOUT, and +VARIADIC +arguments\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Note that +\fBDROP FUNCTION\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type(s) of the function\*(Aqs arguments (optionally schema\-qualified), if any\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the function (such as operators or triggers), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the function if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +This command removes the square root function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP FUNCTION sqrt(integer); +.fi +.if n \{\ +.RE +.\} +.PP +Drop multiple functions in one command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP FUNCTION sqrt(integer), sqrt(bigint); +.fi +.if n \{\ +.RE +.\} +.PP +If the function name is unique in its schema, it can be referred to without an argument list: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP FUNCTION update_employee_salaries; +.fi +.if n \{\ +.RE +.\} +.sp +Note that this is different from +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP FUNCTION update_employee_salaries(); +.fi +.if n \{\ +.RE +.\} +.sp +which refers to a function with zero arguments, whereas the first variant can refer to a function with any number of arguments, including zero, as long as the name is unique\&. +.SH "COMPATIBILITY" +.PP +This command conforms to the SQL standard, with these +PostgreSQL +extensions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The standard only allows one function to be dropped per command\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +IF EXISTS +option +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The ability to specify argument modes and names +.RE +.SH "SEE ALSO" +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)), ALTER FUNCTION (\fBALTER_FUNCTION\fR(7)), DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)), DROP ROUTINE (\fBDROP_ROUTINE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_GROUP.7 b/doc/src/sgml/man7/DROP_GROUP.7 new file mode 100644 index 0000000..9e29135 --- /dev/null +++ b/doc/src/sgml/man7/DROP_GROUP.7 @@ -0,0 +1,48 @@ +'\" t +.\" Title: DROP GROUP +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP GROUP" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_GROUP \- remove a database role +.SH "SYNOPSIS" +.sp +.nf +DROP GROUP [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP GROUP\fR +is now an alias for +\fBDROP ROLE\fR\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP GROUP\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +DROP ROLE (\fBDROP_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_INDEX.7 b/doc/src/sgml/man7/DROP_INDEX.7 new file mode 100644 index 0000000..2dec64a --- /dev/null +++ b/doc/src/sgml/man7/DROP_INDEX.7 @@ -0,0 +1,109 @@ +'\" t +.\" Title: DROP INDEX +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP INDEX" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_INDEX \- remove an index +.SH "SYNOPSIS" +.sp +.nf +DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP INDEX\fR +drops an existing index from the database system\&. To execute this command you must be the owner of the index\&. +.SH "PARAMETERS" +.PP +CONCURRENTLY +.RS 4 +Drop the index without locking out concurrent selects, inserts, updates, and deletes on the index\*(Aqs table\&. A normal +\fBDROP INDEX\fR +acquires an +ACCESS EXCLUSIVE +lock on the table, blocking other accesses until the index drop can be completed\&. With this option, the command instead waits until conflicting transactions have completed\&. +.sp +There are several caveats to be aware of when using this option\&. Only one index name can be specified, and the +CASCADE +option is not supported\&. (Thus, an index that supports a +UNIQUE +or +PRIMARY KEY +constraint cannot be dropped this way\&.) Also, regular +\fBDROP INDEX\fR +commands can be performed within a transaction block, but +\fBDROP INDEX CONCURRENTLY\fR +cannot\&. Lastly, indexes on partitioned tables cannot be dropped using this option\&. +.sp +For temporary tables, +\fBDROP INDEX\fR +is always non\-concurrent, as no other session can access them, and non\-concurrent index drop is cheaper\&. +.RE +.PP +IF EXISTS +.RS 4 +Do not throw an error if the index does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an index to remove\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the index, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the index if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +This command will remove the index +title_idx: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP INDEX title_idx; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP INDEX\fR +is a +PostgreSQL +language extension\&. There are no provisions for indexes in the SQL standard\&. +.SH "SEE ALSO" +CREATE INDEX (\fBCREATE_INDEX\fR(7)) diff --git a/doc/src/sgml/man7/DROP_LANGUAGE.7 b/doc/src/sgml/man7/DROP_LANGUAGE.7 new file mode 100644 index 0000000..26f517e --- /dev/null +++ b/doc/src/sgml/man7/DROP_LANGUAGE.7 @@ -0,0 +1,106 @@ +'\" t +.\" Title: DROP LANGUAGE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP LANGUAGE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_LANGUAGE \- remove a procedural language +.SH "SYNOPSIS" +.sp +.nf +DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP LANGUAGE\fR +removes the definition of a previously registered procedural language\&. You must be a superuser or the owner of the language to use +\fBDROP LANGUAGE\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +As of +PostgreSQL +9\&.1, most procedural languages have been made into +\(lqextensions\(rq, and should therefore be removed with +\fBDROP EXTENSION\fR +not +\fBDROP LANGUAGE\fR\&. +.sp .5v +.RE +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the language does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of an existing procedural language\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the language (such as functions in the language), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the language if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +This command removes the procedural language +plsample: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP LANGUAGE plsample; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP LANGUAGE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER LANGUAGE (\fBALTER_LANGUAGE\fR(7)), CREATE LANGUAGE (\fBCREATE_LANGUAGE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_MATERIALIZED_VIEW.7 b/doc/src/sgml/man7/DROP_MATERIALIZED_VIEW.7 new file mode 100644 index 0000000..ef5b608 --- /dev/null +++ b/doc/src/sgml/man7/DROP_MATERIALIZED_VIEW.7 @@ -0,0 +1,84 @@ +'\" t +.\" Title: DROP MATERIALIZED VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP MATERIALIZED VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_MATERIALIZED_VIEW \- remove a materialized view +.SH "SYNOPSIS" +.sp +.nf +DROP MATERIALIZED VIEW [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP MATERIALIZED VIEW\fR +drops an existing materialized view\&. To execute this command you must be the owner of the materialized view\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the materialized view does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the materialized view to remove\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the materialized view (such as other materialized views, or regular views), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the materialized view if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +This command will remove the materialized view called +order_summary: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP MATERIALIZED VIEW order_summary; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP MATERIALIZED VIEW\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE MATERIALIZED VIEW (\fBCREATE_MATERIALIZED_VIEW\fR(7)), ALTER MATERIALIZED VIEW (\fBALTER_MATERIALIZED_VIEW\fR(7)), REFRESH MATERIALIZED VIEW (\fBREFRESH_MATERIALIZED_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/DROP_OPERATOR.7 b/doc/src/sgml/man7/DROP_OPERATOR.7 new file mode 100644 index 0000000..6f7edc9 --- /dev/null +++ b/doc/src/sgml/man7/DROP_OPERATOR.7 @@ -0,0 +1,124 @@ +'\" t +.\" Title: DROP OPERATOR +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP OPERATOR" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_OPERATOR \- remove an operator +.SH "SYNOPSIS" +.sp +.nf +DROP OPERATOR [ IF EXISTS ] \fIname\fR ( { \fIleft_type\fR | NONE } , \fIright_type\fR ) [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP OPERATOR\fR +drops an existing operator from the database system\&. To execute this command you must be the owner of the operator\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the operator does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing operator\&. +.RE +.PP +\fIleft_type\fR +.RS 4 +The data type of the operator\*(Aqs left operand; write +NONE +if the operator has no left operand\&. +.RE +.PP +\fIright_type\fR +.RS 4 +The data type of the operator\*(Aqs right operand\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the operator (such as views using it), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the operator if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Remove the power operator +a^b +for type +integer: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP OPERATOR ^ (integer, integer); +.fi +.if n \{\ +.RE +.\} +.PP +Remove the bitwise\-complement prefix operator +~b +for type +bit: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP OPERATOR ~ (none, bit); +.fi +.if n \{\ +.RE +.\} +.PP +Remove multiple operators in one command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP OPERATOR ~ (none, bit), ^ (integer, integer); +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP OPERATOR\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +CREATE OPERATOR (\fBCREATE_OPERATOR\fR(7)), ALTER OPERATOR (\fBALTER_OPERATOR\fR(7)) diff --git a/doc/src/sgml/man7/DROP_OPERATOR_CLASS.7 b/doc/src/sgml/man7/DROP_OPERATOR_CLASS.7 new file mode 100644 index 0000000..7afcf2e --- /dev/null +++ b/doc/src/sgml/man7/DROP_OPERATOR_CLASS.7 @@ -0,0 +1,105 @@ +'\" t +.\" Title: DROP OPERATOR CLASS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP OPERATOR CLASS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_OPERATOR_CLASS \- remove an operator class +.SH "SYNOPSIS" +.sp +.nf +DROP OPERATOR CLASS [ IF EXISTS ] \fIname\fR USING \fIindex_method\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP OPERATOR CLASS\fR +drops an existing operator class\&. To execute this command you must be the owner of the operator class\&. +.PP +\fBDROP OPERATOR CLASS\fR +does not drop any of the operators or functions referenced by the class\&. If there are any indexes depending on the operator class, you will need to specify +CASCADE +for the drop to complete\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the operator class does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing operator class\&. +.RE +.PP +\fIindex_method\fR +.RS 4 +The name of the index access method the operator class is for\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the operator class (such as indexes), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the operator class if any objects depend on it\&. This is the default\&. +.RE +.SH "NOTES" +.PP +\fBDROP OPERATOR CLASS\fR +will not drop the operator family containing the class, even if there is nothing else left in the family (in particular, in the case where the family was implicitly created by +\fBCREATE OPERATOR CLASS\fR)\&. An empty operator family is harmless, but for the sake of tidiness you might wish to remove the family with +\fBDROP OPERATOR FAMILY\fR; or perhaps better, use +\fBDROP OPERATOR FAMILY\fR +in the first place\&. +.SH "EXAMPLES" +.PP +Remove the B\-tree operator class +widget_ops: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP OPERATOR CLASS widget_ops USING btree; +.fi +.if n \{\ +.RE +.\} +.sp +This command will not succeed if there are any existing indexes that use the operator class\&. Add +CASCADE +to drop such indexes along with the operator class\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP OPERATOR CLASS\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER OPERATOR CLASS (\fBALTER_OPERATOR_CLASS\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), DROP OPERATOR FAMILY (\fBDROP_OPERATOR_FAMILY\fR(7)) diff --git a/doc/src/sgml/man7/DROP_OPERATOR_FAMILY.7 b/doc/src/sgml/man7/DROP_OPERATOR_FAMILY.7 new file mode 100644 index 0000000..bb8c86e --- /dev/null +++ b/doc/src/sgml/man7/DROP_OPERATOR_FAMILY.7 @@ -0,0 +1,97 @@ +'\" t +.\" Title: DROP OPERATOR FAMILY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP OPERATOR FAMILY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_OPERATOR_FAMILY \- remove an operator family +.SH "SYNOPSIS" +.sp +.nf +DROP OPERATOR FAMILY [ IF EXISTS ] \fIname\fR USING \fIindex_method\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP OPERATOR FAMILY\fR +drops an existing operator family\&. To execute this command you must be the owner of the operator family\&. +.PP +\fBDROP OPERATOR FAMILY\fR +includes dropping any operator classes contained in the family, but it does not drop any of the operators or functions referenced by the family\&. If there are any indexes depending on operator classes within the family, you will need to specify +CASCADE +for the drop to complete\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the operator family does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing operator family\&. +.RE +.PP +\fIindex_method\fR +.RS 4 +The name of the index access method the operator family is for\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the operator family, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the operator family if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Remove the B\-tree operator family +float_ops: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP OPERATOR FAMILY float_ops USING btree; +.fi +.if n \{\ +.RE +.\} +.sp +This command will not succeed if there are any existing indexes that use operator classes within the family\&. Add +CASCADE +to drop such indexes along with the operator family\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP OPERATOR FAMILY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER OPERATOR FAMILY (\fBALTER_OPERATOR_FAMILY\fR(7)), CREATE OPERATOR FAMILY (\fBCREATE_OPERATOR_FAMILY\fR(7)), ALTER OPERATOR CLASS (\fBALTER_OPERATOR_CLASS\fR(7)), CREATE OPERATOR CLASS (\fBCREATE_OPERATOR_CLASS\fR(7)), DROP OPERATOR CLASS (\fBDROP_OPERATOR_CLASS\fR(7)) diff --git a/doc/src/sgml/man7/DROP_OWNED.7 b/doc/src/sgml/man7/DROP_OWNED.7 new file mode 100644 index 0000000..3fd2106 --- /dev/null +++ b/doc/src/sgml/man7/DROP_OWNED.7 @@ -0,0 +1,88 @@ +'\" t +.\" Title: DROP OWNED +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP OWNED" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_OWNED \- remove database objects owned by a database role +.SH "SYNOPSIS" +.sp +.nf +DROP OWNED BY { \fIname\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP OWNED\fR +drops all the objects within the current database that are owned by one of the specified roles\&. Any privileges granted to the given roles on objects in the current database or on shared objects (databases, tablespaces, configuration parameters) will also be revoked\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of a role whose objects will be dropped, and whose privileges will be revoked\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the affected objects, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the objects owned by a role if any other database objects depend on one of the affected objects\&. This is the default\&. +.RE +.SH "NOTES" +.PP +\fBDROP OWNED\fR +is often used to prepare for the removal of one or more roles\&. Because +\fBDROP OWNED\fR +only affects the objects in the current database, it is usually necessary to execute this command in each database that contains objects owned by a role that is to be removed\&. +.PP +Using the +CASCADE +option might make the command recurse to objects owned by other users\&. +.PP +The +\fBREASSIGN OWNED\fR +command is an alternative that reassigns the ownership of all the database objects owned by one or more roles\&. However, +\fBREASSIGN OWNED\fR +does not deal with privileges for other objects\&. +.PP +Databases and tablespaces owned by the role(s) will not be removed\&. +.PP +See +Section\ \&22.4 +for more discussion\&. +.SH "COMPATIBILITY" +.PP +The +\fBDROP OWNED\fR +command is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +REASSIGN OWNED (\fBREASSIGN_OWNED\fR(7)), DROP ROLE (\fBDROP_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_POLICY.7 b/doc/src/sgml/man7/DROP_POLICY.7 new file mode 100644 index 0000000..f5a9c56 --- /dev/null +++ b/doc/src/sgml/man7/DROP_POLICY.7 @@ -0,0 +1,90 @@ +'\" t +.\" Title: DROP POLICY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP POLICY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_POLICY \- remove a row\-level security policy from a table +.SH "SYNOPSIS" +.sp +.nf +DROP POLICY [ IF EXISTS ] \fIname\fR ON \fItable_name\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP POLICY\fR +removes the specified policy from the table\&. Note that if the last policy is removed for a table and the table still has row\-level security enabled via +\fBALTER TABLE\fR, then the default\-deny policy will be used\&. +ALTER TABLE \&.\&.\&. DISABLE ROW LEVEL SECURITY +can be used to disable row\-level security for a table, whether policies for the table exist or not\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the policy does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the policy to drop\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table that the policy is on\&. +.RE +.PP +CASCADE +.br +RESTRICT +.RS 4 +These key words do not have any effect, since there are no dependencies on policies\&. +.RE +.SH "EXAMPLES" +.PP +To drop the policy called +p1 +on the table named +my_table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP POLICY p1 ON my_table; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP POLICY\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE POLICY (\fBCREATE_POLICY\fR(7)), ALTER POLICY (\fBALTER_POLICY\fR(7)) diff --git a/doc/src/sgml/man7/DROP_PROCEDURE.7 b/doc/src/sgml/man7/DROP_PROCEDURE.7 new file mode 100644 index 0000000..7be733e --- /dev/null +++ b/doc/src/sgml/man7/DROP_PROCEDURE.7 @@ -0,0 +1,220 @@ +'\" t +.\" Title: DROP PROCEDURE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP PROCEDURE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_PROCEDURE \- remove a procedure +.SH "SYNOPSIS" +.sp +.nf +DROP PROCEDURE [ IF EXISTS ] \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] [, \&.\&.\&.] + [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP PROCEDURE\fR +removes the definition of one or more existing procedures\&. To execute this command the user must be the owner of the procedure(s)\&. The argument types to the procedure(s) usually must be specified, since several different procedures can exist with the same name and different argument lists\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the procedure does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing procedure\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of an argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN +(but see below)\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of an argument\&. Note that +\fBDROP PROCEDURE\fR +does not actually pay any attention to argument names, since only the argument data types are used to determine the procedure\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type(s) of the procedure\*(Aqs arguments (optionally schema\-qualified), if any\&. See below for details\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the procedure, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the procedure if any objects depend on it\&. This is the default\&. +.RE +.SH "NOTES" +.PP +If there is only one procedure of the given name, the argument list can be omitted\&. Omit the parentheses too in this case\&. +.PP +In +PostgreSQL, it\*(Aqs sufficient to list the input (including +INOUT) arguments, because no two routines of the same name are allowed to share the same input\-argument list\&. Moreover, the +\fBDROP\fR +command will not actually check that you wrote the types of +OUT +arguments correctly; so any arguments that are explicitly marked +OUT +are just noise\&. But writing them is recommendable for consistency with the corresponding +\fBCREATE\fR +command\&. +.PP +For compatibility with the SQL standard, it is also allowed to write all the argument data types (including those of +OUT +arguments) without any +\fIargmode\fR +markers\&. When this is done, the types of the procedure\*(Aqs +OUT +argument(s) +\fIwill\fR +be verified against the command\&. This provision creates an ambiguity, in that when the argument list contains no +\fIargmode\fR +markers, it\*(Aqs unclear which rule is intended\&. The +\fBDROP\fR +command will attempt the lookup both ways, and will throw an error if two different procedures are found\&. To avoid the risk of such ambiguity, it\*(Aqs recommendable to write +IN +markers explicitly rather than letting them be defaulted, thus forcing the traditional +PostgreSQL +interpretation to be used\&. +.PP +The lookup rules just explained are also used by other commands that act on existing procedures, such as +\fBALTER PROCEDURE\fR +and +\fBCOMMENT ON PROCEDURE\fR\&. +.SH "EXAMPLES" +.PP +If there is only one procedure +do_db_maintenance, this command is sufficient to drop it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP PROCEDURE do_db_maintenance; +.fi +.if n \{\ +.RE +.\} +.PP +Given this procedure definition: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PROCEDURE do_db_maintenance(IN target_schema text, OUT results text) \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.sp +any one of these commands would work to drop it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP PROCEDURE do_db_maintenance(IN target_schema text, OUT results text); +DROP PROCEDURE do_db_maintenance(IN text, OUT text); +DROP PROCEDURE do_db_maintenance(IN text); +DROP PROCEDURE do_db_maintenance(text); +DROP PROCEDURE do_db_maintenance(text, text); \-\- potentially ambiguous +.fi +.if n \{\ +.RE +.\} +.sp +However, the last example would be ambiguous if there is also, say, +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE PROCEDURE do_db_maintenance(IN target_schema text, IN options text) \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to the SQL standard, with these +PostgreSQL +extensions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The standard only allows one procedure to be dropped per command\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +IF EXISTS +option is an extension\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The ability to specify argument modes and names is an extension, and the lookup rules differ when modes are given\&. +.RE +.SH "SEE ALSO" +CREATE PROCEDURE (\fBCREATE_PROCEDURE\fR(7)), ALTER PROCEDURE (\fBALTER_PROCEDURE\fR(7)), DROP FUNCTION (\fBDROP_FUNCTION\fR(7)), DROP ROUTINE (\fBDROP_ROUTINE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_PUBLICATION.7 b/doc/src/sgml/man7/DROP_PUBLICATION.7 new file mode 100644 index 0000000..5cc2fe5 --- /dev/null +++ b/doc/src/sgml/man7/DROP_PUBLICATION.7 @@ -0,0 +1,81 @@ +'\" t +.\" Title: DROP PUBLICATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP PUBLICATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_PUBLICATION \- remove a publication +.SH "SYNOPSIS" +.sp +.nf +DROP PUBLICATION [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP PUBLICATION\fR +removes an existing publication from the database\&. +.PP +A publication can only be dropped by its owner or a superuser\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the publication does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of an existing publication\&. +.RE +.PP +CASCADE +.br +RESTRICT +.RS 4 +These key words do not have any effect, since there are no dependencies on publications\&. +.RE +.SH "EXAMPLES" +.PP +Drop a publication: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP PUBLICATION mypublication; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP PUBLICATION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE PUBLICATION (\fBCREATE_PUBLICATION\fR(7)), ALTER PUBLICATION (\fBALTER_PUBLICATION\fR(7)) diff --git a/doc/src/sgml/man7/DROP_ROLE.7 b/doc/src/sgml/man7/DROP_ROLE.7 new file mode 100644 index 0000000..f64c121 --- /dev/null +++ b/doc/src/sgml/man7/DROP_ROLE.7 @@ -0,0 +1,92 @@ +'\" t +.\" Title: DROP ROLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP ROLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_ROLE \- remove a database role +.SH "SYNOPSIS" +.sp +.nf +DROP ROLE [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP ROLE\fR +removes the specified role(s)\&. To drop a superuser role, you must be a superuser yourself; to drop non\-superuser roles, you must have +CREATEROLE +privilege\&. +.PP +A role cannot be removed if it is still referenced in any database of the cluster; an error will be raised if so\&. Before dropping the role, you must drop all the objects it owns (or reassign their ownership) and revoke any privileges the role has been granted on other objects\&. The +\fBREASSIGN OWNED\fR +and +\fBDROP OWNED\fR +commands can be useful for this purpose; see +Section\ \&22.4 +for more discussion\&. +.PP +However, it is not necessary to remove role memberships involving the role; +\fBDROP ROLE\fR +automatically revokes any memberships of the target role in other roles, and of other roles in the target role\&. The other roles are not dropped nor otherwise affected\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the role does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the role to remove\&. +.RE +.SH "NOTES" +.PP +PostgreSQL +includes a program +\fBdropuser\fR(1) +that has the same functionality as this command (in fact, it calls this command) but can be run from the command shell\&. +.SH "EXAMPLES" +.PP +To drop a role: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP ROLE jonathan; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The SQL standard defines +\fBDROP ROLE\fR, but it allows only one role to be dropped at a time, and it specifies different privilege requirements than +PostgreSQL +uses\&. +.SH "SEE ALSO" +CREATE ROLE (\fBCREATE_ROLE\fR(7)), ALTER ROLE (\fBALTER_ROLE\fR(7)), SET ROLE (\fBSET_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_ROUTINE.7 b/doc/src/sgml/man7/DROP_ROUTINE.7 new file mode 100644 index 0000000..43acbac --- /dev/null +++ b/doc/src/sgml/man7/DROP_ROUTINE.7 @@ -0,0 +1,148 @@ +'\" t +.\" Title: DROP ROUTINE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP ROUTINE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_ROUTINE \- remove a routine +.SH "SYNOPSIS" +.sp +.nf +DROP ROUTINE [ IF EXISTS ] \fIname\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] [, \&.\&.\&.] + [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP ROUTINE\fR +removes the definition of one or more existing routines\&. The term +\(lqroutine\(rq +includes aggregate functions, normal functions, and procedures\&. See under +DROP AGGREGATE (\fBDROP_AGGREGATE\fR(7)), +DROP FUNCTION (\fBDROP_FUNCTION\fR(7)), and +DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)) +for the description of the parameters, more examples, and further details\&. +.SH "NOTES" +.PP +The lookup rules used by +\fBDROP ROUTINE\fR +are fundamentally the same as for +\fBDROP PROCEDURE\fR; in particular, +\fBDROP ROUTINE\fR +shares that command\*(Aqs behavior of considering an argument list that has no +\fIargmode\fR +markers to be possibly using the SQL standard\*(Aqs definition that +OUT +arguments are included in the list\&. (\fBDROP AGGREGATE\fR +and +\fBDROP FUNCTION\fR +do not do that\&.) +.PP +In some cases where the same name is shared by routines of different kinds, it is possible for +\fBDROP ROUTINE\fR +to fail with an ambiguity error when a more specific command (\fBDROP FUNCTION\fR, etc\&.) would work\&. Specifying the argument type list more carefully will also resolve such problems\&. +.PP +These lookup rules are also used by other commands that act on existing routines, such as +\fBALTER ROUTINE\fR +and +\fBCOMMENT ON ROUTINE\fR\&. +.SH "EXAMPLES" +.PP +To drop the routine +foo +for type +integer: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP ROUTINE foo(integer); +.fi +.if n \{\ +.RE +.\} +.sp +This command will work independent of whether +foo +is an aggregate, function, or procedure\&. +.SH "COMPATIBILITY" +.PP +This command conforms to the SQL standard, with these +PostgreSQL +extensions: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The standard only allows one routine to be dropped per command\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The +IF EXISTS +option is an extension\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +The ability to specify argument modes and names is an extension, and the lookup rules differ when modes are given\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +User\-definable aggregate functions are an extension\&. +.RE +.SH "SEE ALSO" +DROP AGGREGATE (\fBDROP_AGGREGATE\fR(7)), DROP FUNCTION (\fBDROP_FUNCTION\fR(7)), DROP PROCEDURE (\fBDROP_PROCEDURE\fR(7)), ALTER ROUTINE (\fBALTER_ROUTINE\fR(7)) +.PP +Note that there is no +CREATE ROUTINE +command\&. diff --git a/doc/src/sgml/man7/DROP_RULE.7 b/doc/src/sgml/man7/DROP_RULE.7 new file mode 100644 index 0000000..0f2a311 --- /dev/null +++ b/doc/src/sgml/man7/DROP_RULE.7 @@ -0,0 +1,89 @@ +'\" t +.\" Title: DROP RULE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP RULE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_RULE \- remove a rewrite rule +.SH "SYNOPSIS" +.sp +.nf +DROP RULE [ IF EXISTS ] \fIname\fR ON \fItable_name\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP RULE\fR +drops a rewrite rule\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the rule does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the rule to drop\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table or view that the rule applies to\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the rule, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the rule if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To drop the rewrite rule +newrule: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP RULE newrule ON mytable; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP RULE\fR +is a +PostgreSQL +language extension, as is the entire query rewrite system\&. +.SH "SEE ALSO" +CREATE RULE (\fBCREATE_RULE\fR(7)), ALTER RULE (\fBALTER_RULE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_SCHEMA.7 b/doc/src/sgml/man7/DROP_SCHEMA.7 new file mode 100644 index 0000000..d5d65fb --- /dev/null +++ b/doc/src/sgml/man7/DROP_SCHEMA.7 @@ -0,0 +1,94 @@ +'\" t +.\" Title: DROP SCHEMA +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP SCHEMA" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_SCHEMA \- remove a schema +.SH "SYNOPSIS" +.sp +.nf +DROP SCHEMA [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP SCHEMA\fR +removes schemas from the database\&. +.PP +A schema can only be dropped by its owner or a superuser\&. Note that the owner can drop the schema (and thereby all contained objects) even if they do not own some of the objects within the schema\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the schema does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of a schema\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects (tables, functions, etc\&.) that are contained in the schema, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the schema if it contains any objects\&. This is the default\&. +.RE +.SH "NOTES" +.PP +Using the +CASCADE +option might make the command remove objects in other schemas besides the one(s) named\&. +.SH "EXAMPLES" +.PP +To remove schema +mystuff +from the database, along with everything it contains: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP SCHEMA mystuff CASCADE; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP SCHEMA\fR +is fully conforming with the SQL standard, except that the standard only allows one schema to be dropped per command, and apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER SCHEMA (\fBALTER_SCHEMA\fR(7)), CREATE SCHEMA (\fBCREATE_SCHEMA\fR(7)) diff --git a/doc/src/sgml/man7/DROP_SEQUENCE.7 b/doc/src/sgml/man7/DROP_SEQUENCE.7 new file mode 100644 index 0000000..5993e60 --- /dev/null +++ b/doc/src/sgml/man7/DROP_SEQUENCE.7 @@ -0,0 +1,88 @@ +'\" t +.\" Title: DROP SEQUENCE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP SEQUENCE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_SEQUENCE \- remove a sequence +.SH "SYNOPSIS" +.sp +.nf +DROP SEQUENCE [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP SEQUENCE\fR +removes sequence number generators\&. A sequence can only be dropped by its owner or a superuser\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the sequence does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of a sequence\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the sequence, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the sequence if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To remove the sequence +serial: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP SEQUENCE serial; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP SEQUENCE\fR +conforms to the +SQL +standard, except that the standard only allows one sequence to be dropped per command, and apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE SEQUENCE (\fBCREATE_SEQUENCE\fR(7)), ALTER SEQUENCE (\fBALTER_SEQUENCE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_SERVER.7 b/doc/src/sgml/man7/DROP_SERVER.7 new file mode 100644 index 0000000..65412ee --- /dev/null +++ b/doc/src/sgml/man7/DROP_SERVER.7 @@ -0,0 +1,87 @@ +'\" t +.\" Title: DROP SERVER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP SERVER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_SERVER \- remove a foreign server descriptor +.SH "SYNOPSIS" +.sp +.nf +DROP SERVER [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP SERVER\fR +removes an existing foreign server descriptor\&. To execute this command, the current user must be the owner of the server\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the server does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of an existing server\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the server (such as user mappings), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the server if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Drop a server +foo +if it exists: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP SERVER IF EXISTS foo; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP SERVER\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. The +IF EXISTS +clause is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE SERVER (\fBCREATE_SERVER\fR(7)), ALTER SERVER (\fBALTER_SERVER\fR(7)) diff --git a/doc/src/sgml/man7/DROP_STATISTICS.7 b/doc/src/sgml/man7/DROP_STATISTICS.7 new file mode 100644 index 0000000..bc7675a --- /dev/null +++ b/doc/src/sgml/man7/DROP_STATISTICS.7 @@ -0,0 +1,80 @@ +'\" t +.\" Title: DROP STATISTICS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP STATISTICS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_STATISTICS \- remove extended statistics +.SH "SYNOPSIS" +.sp +.nf +DROP STATISTICS [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP STATISTICS\fR +removes statistics object(s) from the database\&. Only the statistics object\*(Aqs owner, the schema owner, or a superuser can drop a statistics object\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the statistics object does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the statistics object to drop\&. +.RE +.PP +CASCADE +.br +RESTRICT +.RS 4 +These key words do not have any effect, since there are no dependencies on statistics\&. +.RE +.SH "EXAMPLES" +.PP +To destroy two statistics objects in different schemas, without failing if they don\*(Aqt exist: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP STATISTICS IF EXISTS + accounting\&.users_uid_creation, + public\&.grants_user_role; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP STATISTICS\fR +command in the SQL standard\&. +.SH "SEE ALSO" +ALTER STATISTICS (\fBALTER_STATISTICS\fR(7)), CREATE STATISTICS (\fBCREATE_STATISTICS\fR(7)) diff --git a/doc/src/sgml/man7/DROP_SUBSCRIPTION.7 b/doc/src/sgml/man7/DROP_SUBSCRIPTION.7 new file mode 100644 index 0000000..1402b21 --- /dev/null +++ b/doc/src/sgml/man7/DROP_SUBSCRIPTION.7 @@ -0,0 +1,97 @@ +'\" t +.\" Title: DROP SUBSCRIPTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP SUBSCRIPTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_SUBSCRIPTION \- remove a subscription +.SH "SYNOPSIS" +.sp +.nf +DROP SUBSCRIPTION [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP SUBSCRIPTION\fR +removes a subscription from the database cluster\&. +.PP +A subscription can only be dropped by a superuser\&. +.PP +\fBDROP SUBSCRIPTION\fR +cannot be executed inside a transaction block if the subscription is associated with a replication slot\&. (You can use +\fBALTER SUBSCRIPTION\fR +to unset the slot\&.) +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of a subscription to be dropped\&. +.RE +.PP +CASCADE +.br +RESTRICT +.RS 4 +These key words do not have any effect, since there are no dependencies on subscriptions\&. +.RE +.SH "NOTES" +.PP +When dropping a subscription that is associated with a replication slot on the remote host (the normal state), +\fBDROP SUBSCRIPTION\fR +will connect to the remote host and try to drop the replication slot (and any remaining table synchronization slots) as part of its operation\&. This is necessary so that the resources allocated for the subscription on the remote host are released\&. If this fails, either because the remote host is not reachable or because the remote replication slot cannot be dropped or does not exist or never existed, the +\fBDROP SUBSCRIPTION\fR +command will fail\&. To proceed in this situation, first disable the subscription by executing +ALTER SUBSCRIPTION \&.\&.\&. DISABLE, and then disassociate it from the replication slot by executing +ALTER SUBSCRIPTION \&.\&.\&. SET (slot_name = NONE)\&. After that, +\fBDROP SUBSCRIPTION\fR +will no longer attempt any actions on a remote host\&. Note that if the remote replication slot still exists, it (and any related table synchronization slots) should then be dropped manually; otherwise it/they will continue to reserve WAL and might eventually cause the disk to fill up\&. See also +Section\ \&31.2.1\&. +.PP +If a subscription is associated with a replication slot, then +\fBDROP SUBSCRIPTION\fR +cannot be executed inside a transaction block\&. +.SH "EXAMPLES" +.PP +Drop a subscription: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP SUBSCRIPTION mysub; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP SUBSCRIPTION\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE SUBSCRIPTION (\fBCREATE_SUBSCRIPTION\fR(7)), ALTER SUBSCRIPTION (\fBALTER_SUBSCRIPTION\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TABLE.7 b/doc/src/sgml/man7/DROP_TABLE.7 new file mode 100644 index 0000000..f282f33 --- /dev/null +++ b/doc/src/sgml/man7/DROP_TABLE.7 @@ -0,0 +1,96 @@ +'\" t +.\" Title: DROP TABLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TABLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TABLE \- remove a table +.SH "SYNOPSIS" +.sp +.nf +DROP TABLE [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TABLE\fR +removes tables from the database\&. Only the table owner, the schema owner, and superuser can drop a table\&. To empty a table of rows without destroying the table, use +\fBDELETE\fR +or +\fBTRUNCATE\fR\&. +.PP +\fBDROP TABLE\fR +always removes any indexes, rules, triggers, and constraints that exist for the target table\&. However, to drop a table that is referenced by a view or a foreign\-key constraint of another table, +CASCADE +must be specified\&. (CASCADE +will remove a dependent view entirely, but in the foreign\-key case it will only remove the foreign\-key constraint, not the other table entirely\&.) +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the table does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the table to drop\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the table (such as views), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the table if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To destroy two tables, +films +and +distributors: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TABLE films, distributors; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to the SQL standard, except that the standard only allows one table to be dropped per command, and apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER TABLE (\fBALTER_TABLE\fR(7)), CREATE TABLE (\fBCREATE_TABLE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TABLESPACE.7 b/doc/src/sgml/man7/DROP_TABLESPACE.7 new file mode 100644 index 0000000..138c0fc --- /dev/null +++ b/doc/src/sgml/man7/DROP_TABLESPACE.7 @@ -0,0 +1,84 @@ +'\" t +.\" Title: DROP TABLESPACE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TABLESPACE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TABLESPACE \- remove a tablespace +.SH "SYNOPSIS" +.sp +.nf +DROP TABLESPACE [ IF EXISTS ] \fIname\fR +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TABLESPACE\fR +removes a tablespace from the system\&. +.PP +A tablespace can only be dropped by its owner or a superuser\&. The tablespace must be empty of all database objects before it can be dropped\&. It is possible that objects in other databases might still reside in the tablespace even if no objects in the current database are using the tablespace\&. Also, if the tablespace is listed in the +temp_tablespaces +setting of any active session, the +\fBDROP\fR +might fail due to temporary files residing in the tablespace\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the tablespace does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of a tablespace\&. +.RE +.SH "NOTES" +.PP +\fBDROP TABLESPACE\fR +cannot be executed inside a transaction block\&. +.SH "EXAMPLES" +.PP +To remove tablespace +mystuff +from the system: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TABLESPACE mystuff; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP TABLESPACE\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE TABLESPACE (\fBCREATE_TABLESPACE\fR(7)), ALTER TABLESPACE (\fBALTER_TABLESPACE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TEXT_SEARCH_CONFIGURATION.7 b/doc/src/sgml/man7/DROP_TEXT_SEARCH_CONFIGURATION.7 new file mode 100644 index 0000000..06b0eec --- /dev/null +++ b/doc/src/sgml/man7/DROP_TEXT_SEARCH_CONFIGURATION.7 @@ -0,0 +1,89 @@ +'\" t +.\" Title: DROP TEXT SEARCH CONFIGURATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TEXT SEARCH CONFIGURATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TEXT_SEARCH_CONFIGURATION \- remove a text search configuration +.SH "SYNOPSIS" +.sp +.nf +DROP TEXT SEARCH CONFIGURATION [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TEXT SEARCH CONFIGURATION\fR +drops an existing text search configuration\&. To execute this command you must be the owner of the configuration\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the text search configuration does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search configuration\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the text search configuration, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the text search configuration if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Remove the text search configuration +my_english: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TEXT SEARCH CONFIGURATION my_english; +.fi +.if n \{\ +.RE +.\} +.sp +This command will not succeed if there are any existing indexes that reference the configuration in +\fBto_tsvector\fR +calls\&. Add +CASCADE +to drop such indexes along with the text search configuration\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP TEXT SEARCH CONFIGURATION\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH CONFIGURATION (\fBALTER_TEXT_SEARCH_CONFIGURATION\fR(7)), CREATE TEXT SEARCH CONFIGURATION (\fBCREATE_TEXT_SEARCH_CONFIGURATION\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TEXT_SEARCH_DICTIONARY.7 b/doc/src/sgml/man7/DROP_TEXT_SEARCH_DICTIONARY.7 new file mode 100644 index 0000000..92c7d74 --- /dev/null +++ b/doc/src/sgml/man7/DROP_TEXT_SEARCH_DICTIONARY.7 @@ -0,0 +1,87 @@ +'\" t +.\" Title: DROP TEXT SEARCH DICTIONARY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TEXT SEARCH DICTIONARY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TEXT_SEARCH_DICTIONARY \- remove a text search dictionary +.SH "SYNOPSIS" +.sp +.nf +DROP TEXT SEARCH DICTIONARY [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TEXT SEARCH DICTIONARY\fR +drops an existing text search dictionary\&. To execute this command you must be the owner of the dictionary\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the text search dictionary does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search dictionary\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the text search dictionary, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the text search dictionary if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Remove the text search dictionary +english: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TEXT SEARCH DICTIONARY english; +.fi +.if n \{\ +.RE +.\} +.sp +This command will not succeed if there are any existing text search configurations that use the dictionary\&. Add +CASCADE +to drop such configurations along with the dictionary\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP TEXT SEARCH DICTIONARY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH DICTIONARY (\fBALTER_TEXT_SEARCH_DICTIONARY\fR(7)), CREATE TEXT SEARCH DICTIONARY (\fBCREATE_TEXT_SEARCH_DICTIONARY\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TEXT_SEARCH_PARSER.7 b/doc/src/sgml/man7/DROP_TEXT_SEARCH_PARSER.7 new file mode 100644 index 0000000..370a3aa --- /dev/null +++ b/doc/src/sgml/man7/DROP_TEXT_SEARCH_PARSER.7 @@ -0,0 +1,87 @@ +'\" t +.\" Title: DROP TEXT SEARCH PARSER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TEXT SEARCH PARSER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TEXT_SEARCH_PARSER \- remove a text search parser +.SH "SYNOPSIS" +.sp +.nf +DROP TEXT SEARCH PARSER [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TEXT SEARCH PARSER\fR +drops an existing text search parser\&. You must be a superuser to use this command\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the text search parser does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search parser\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the text search parser, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the text search parser if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Remove the text search parser +my_parser: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TEXT SEARCH PARSER my_parser; +.fi +.if n \{\ +.RE +.\} +.sp +This command will not succeed if there are any existing text search configurations that use the parser\&. Add +CASCADE +to drop such configurations along with the parser\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP TEXT SEARCH PARSER\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH PARSER (\fBALTER_TEXT_SEARCH_PARSER\fR(7)), CREATE TEXT SEARCH PARSER (\fBCREATE_TEXT_SEARCH_PARSER\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TEXT_SEARCH_TEMPLATE.7 b/doc/src/sgml/man7/DROP_TEXT_SEARCH_TEMPLATE.7 new file mode 100644 index 0000000..400265b --- /dev/null +++ b/doc/src/sgml/man7/DROP_TEXT_SEARCH_TEMPLATE.7 @@ -0,0 +1,87 @@ +'\" t +.\" Title: DROP TEXT SEARCH TEMPLATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TEXT SEARCH TEMPLATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TEXT_SEARCH_TEMPLATE \- remove a text search template +.SH "SYNOPSIS" +.sp +.nf +DROP TEXT SEARCH TEMPLATE [ IF EXISTS ] \fIname\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TEXT SEARCH TEMPLATE\fR +drops an existing text search template\&. You must be a superuser to use this command\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the text search template does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing text search template\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the text search template, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the text search template if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Remove the text search template +thesaurus: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TEXT SEARCH TEMPLATE thesaurus; +.fi +.if n \{\ +.RE +.\} +.sp +This command will not succeed if there are any existing text search dictionaries that use the template\&. Add +CASCADE +to drop such dictionaries along with the template\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBDROP TEXT SEARCH TEMPLATE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +ALTER TEXT SEARCH TEMPLATE (\fBALTER_TEXT_SEARCH_TEMPLATE\fR(7)), CREATE TEXT SEARCH TEMPLATE (\fBCREATE_TEXT_SEARCH_TEMPLATE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TRANSFORM.7 b/doc/src/sgml/man7/DROP_TRANSFORM.7 new file mode 100644 index 0000000..d1cd290 --- /dev/null +++ b/doc/src/sgml/man7/DROP_TRANSFORM.7 @@ -0,0 +1,96 @@ +'\" t +.\" Title: DROP TRANSFORM +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TRANSFORM" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TRANSFORM \- remove a transform +.SH "SYNOPSIS" +.sp +.nf +DROP TRANSFORM [ IF EXISTS ] FOR \fItype_name\fR LANGUAGE \fIlang_name\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TRANSFORM\fR +removes a previously defined transform\&. +.PP +To be able to drop a transform, you must own the type and the language\&. These are the same privileges that are required to create a transform\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the transform does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fItype_name\fR +.RS 4 +The name of the data type of the transform\&. +.RE +.PP +\fIlang_name\fR +.RS 4 +The name of the language of the transform\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the transform, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the transform if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To drop the transform for type +hstore +and language +plpython3u: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TRANSFORM FOR hstore LANGUAGE plpython3u; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This form of +\fBDROP TRANSFORM\fR +is a +PostgreSQL +extension\&. See +CREATE TRANSFORM (\fBCREATE_TRANSFORM\fR(7)) +for details\&. +.SH "SEE ALSO" +CREATE TRANSFORM (\fBCREATE_TRANSFORM\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TRIGGER.7 b/doc/src/sgml/man7/DROP_TRIGGER.7 new file mode 100644 index 0000000..768d105 --- /dev/null +++ b/doc/src/sgml/man7/DROP_TRIGGER.7 @@ -0,0 +1,93 @@ +'\" t +.\" Title: DROP TRIGGER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TRIGGER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TRIGGER \- remove a trigger +.SH "SYNOPSIS" +.sp +.nf +DROP TRIGGER [ IF EXISTS ] \fIname\fR ON \fItable_name\fR [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TRIGGER\fR +removes an existing trigger definition\&. To execute this command, the current user must be the owner of the table for which the trigger is defined\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the trigger does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the trigger to remove\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table for which the trigger is defined\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the trigger, and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the trigger if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +Destroy the trigger +if_dist_exists +on the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TRIGGER if_dist_exists ON films; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBDROP TRIGGER\fR +statement in +PostgreSQL +is incompatible with the SQL standard\&. In the SQL standard, trigger names are not local to tables, so the command is simply +DROP TRIGGER \fIname\fR\&. +.SH "SEE ALSO" +CREATE TRIGGER (\fBCREATE_TRIGGER\fR(7)) diff --git a/doc/src/sgml/man7/DROP_TYPE.7 b/doc/src/sgml/man7/DROP_TYPE.7 new file mode 100644 index 0000000..94b140b --- /dev/null +++ b/doc/src/sgml/man7/DROP_TYPE.7 @@ -0,0 +1,89 @@ +'\" t +.\" Title: DROP TYPE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP TYPE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_TYPE \- remove a data type +.SH "SYNOPSIS" +.sp +.nf +DROP TYPE [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP TYPE\fR +removes a user\-defined data type\&. Only the owner of a type can remove it\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the type does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the data type to remove\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the type (such as table columns, functions, and operators), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the type if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +To remove the data type +box: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP TYPE box; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command is similar to the corresponding command in the SQL standard, apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. But note that much of the +\fBCREATE TYPE\fR +command and the data type extension mechanisms in +PostgreSQL +differ from the SQL standard\&. +.SH "SEE ALSO" +ALTER TYPE (\fBALTER_TYPE\fR(7)), CREATE TYPE (\fBCREATE_TYPE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_USER.7 b/doc/src/sgml/man7/DROP_USER.7 new file mode 100644 index 0000000..76656d1 --- /dev/null +++ b/doc/src/sgml/man7/DROP_USER.7 @@ -0,0 +1,50 @@ +'\" t +.\" Title: DROP USER +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP USER" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_USER \- remove a database role +.SH "SYNOPSIS" +.sp +.nf +DROP USER [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP USER\fR +is simply an alternate spelling of +\fBDROP ROLE\fR\&. +.SH "COMPATIBILITY" +.PP +The +\fBDROP USER\fR +statement is a +PostgreSQL +extension\&. The SQL standard leaves the definition of users to the implementation\&. +.SH "SEE ALSO" +DROP ROLE (\fBDROP_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/DROP_USER_MAPPING.7 b/doc/src/sgml/man7/DROP_USER_MAPPING.7 new file mode 100644 index 0000000..3777766 --- /dev/null +++ b/doc/src/sgml/man7/DROP_USER_MAPPING.7 @@ -0,0 +1,92 @@ +'\" t +.\" Title: DROP USER MAPPING +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP USER MAPPING" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_USER_MAPPING \- remove a user mapping for a foreign server +.SH "SYNOPSIS" +.sp +.nf +DROP USER MAPPING [ IF EXISTS ] FOR { \fIuser_name\fR | USER | CURRENT_ROLE | CURRENT_USER | PUBLIC } SERVER \fIserver_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBDROP USER MAPPING\fR +removes an existing user mapping from foreign server\&. +.PP +The owner of a foreign server can drop user mappings for that server for any user\&. Also, a user can drop a user mapping for their own user name if +USAGE +privilege on the server has been granted to the user\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the user mapping does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIuser_name\fR +.RS 4 +User name of the mapping\&. +CURRENT_ROLE, +CURRENT_USER, and +USER +match the name of the current user\&. +PUBLIC +is used to match all present and future user names in the system\&. +.RE +.PP +\fIserver_name\fR +.RS 4 +Server name of the user mapping\&. +.RE +.SH "EXAMPLES" +.PP +Drop a user mapping +bob, server +foo +if it exists: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP USER MAPPING IF EXISTS FOR bob SERVER foo; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBDROP USER MAPPING\fR +conforms to ISO/IEC 9075\-9 (SQL/MED)\&. The +IF EXISTS +clause is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE USER MAPPING (\fBCREATE_USER_MAPPING\fR(7)), ALTER USER MAPPING (\fBALTER_USER_MAPPING\fR(7)) diff --git a/doc/src/sgml/man7/DROP_VIEW.7 b/doc/src/sgml/man7/DROP_VIEW.7 new file mode 100644 index 0000000..3875a18 --- /dev/null +++ b/doc/src/sgml/man7/DROP_VIEW.7 @@ -0,0 +1,85 @@ +'\" t +.\" Title: DROP VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "DROP VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +DROP_VIEW \- remove a view +.SH "SYNOPSIS" +.sp +.nf +DROP VIEW [ IF EXISTS ] \fIname\fR [, \&.\&.\&.] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBDROP VIEW\fR +drops an existing view\&. To execute this command you must be the owner of the view\&. +.SH "PARAMETERS" +.PP +IF EXISTS +.RS 4 +Do not throw an error if the view does not exist\&. A notice is issued in this case\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the view to remove\&. +.RE +.PP +CASCADE +.RS 4 +Automatically drop objects that depend on the view (such as other views), and in turn all objects that depend on those objects (see +Section\ \&5.14)\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to drop the view if any objects depend on it\&. This is the default\&. +.RE +.SH "EXAMPLES" +.PP +This command will remove the view called +kinds: +.sp +.if n \{\ +.RS 4 +.\} +.nf +DROP VIEW kinds; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to the SQL standard, except that the standard only allows one view to be dropped per command, and apart from the +IF EXISTS +option, which is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +ALTER VIEW (\fBALTER_VIEW\fR(7)), CREATE VIEW (\fBCREATE_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/END.7 b/doc/src/sgml/man7/END.7 new file mode 100644 index 0000000..5ed3f9f --- /dev/null +++ b/doc/src/sgml/man7/END.7 @@ -0,0 +1,90 @@ +'\" t +.\" Title: END +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "END" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +END \- commit the current transaction +.SH "SYNOPSIS" +.sp +.nf +END [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] +.fi +.SH "DESCRIPTION" +.PP +\fBEND\fR +commits the current transaction\&. All changes made by the transaction become visible to others and are guaranteed to be durable if a crash occurs\&. This command is a +PostgreSQL +extension that is equivalent to +\fBCOMMIT\fR\&. +.SH "PARAMETERS" +.PP +WORK +.br +TRANSACTION +.RS 4 +Optional key words\&. They have no effect\&. +.RE +.PP +AND CHAIN +.RS 4 +If +AND CHAIN +is specified, a new transaction is immediately started with the same transaction characteristics (see +SET TRANSACTION (\fBSET_TRANSACTION\fR(7))) as the just finished one\&. Otherwise, no new transaction is started\&. +.RE +.SH "NOTES" +.PP +Use +\fBROLLBACK\fR +to abort a transaction\&. +.PP +Issuing +\fBEND\fR +when not inside a transaction does no harm, but it will provoke a warning message\&. +.SH "EXAMPLES" +.PP +To commit the current transaction and make all changes permanent: +.sp +.if n \{\ +.RS 4 +.\} +.nf +END; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBEND\fR +is a +PostgreSQL +extension that provides functionality equivalent to +\fBCOMMIT\fR, which is specified in the SQL standard\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), \fBROLLBACK\fR(7) diff --git a/doc/src/sgml/man7/EXECUTE.7 b/doc/src/sgml/man7/EXECUTE.7 new file mode 100644 index 0000000..4ac1b6c --- /dev/null +++ b/doc/src/sgml/man7/EXECUTE.7 @@ -0,0 +1,84 @@ +'\" t +.\" Title: EXECUTE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "EXECUTE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +EXECUTE \- execute a prepared statement +.SH "SYNOPSIS" +.sp +.nf +EXECUTE \fIname\fR [ ( \fIparameter\fR [, \&.\&.\&.] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBEXECUTE\fR +is used to execute a previously prepared statement\&. Since prepared statements only exist for the duration of a session, the prepared statement must have been created by a +\fBPREPARE\fR +statement executed earlier in the current session\&. +.PP +If the +\fBPREPARE\fR +statement that created the statement specified some parameters, a compatible set of parameters must be passed to the +\fBEXECUTE\fR +statement, or else an error is raised\&. Note that (unlike functions) prepared statements are not overloaded based on the type or number of their parameters; the name of a prepared statement must be unique within a database session\&. +.PP +For more information on the creation and usage of prepared statements, see +\fBPREPARE\fR(7)\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of the prepared statement to execute\&. +.RE +.PP +\fIparameter\fR +.RS 4 +The actual value of a parameter to the prepared statement\&. This must be an expression yielding a value that is compatible with the data type of this parameter, as was determined when the prepared statement was created\&. +.RE +.SH "OUTPUTS" +.PP +The command tag returned by +\fBEXECUTE\fR +is that of the prepared statement, and not +EXECUTE\&. +.SH "EXAMPLES" +.PP +Examples are given in +Examples +in the +\fBPREPARE\fR(7) +documentation\&. +.SH "COMPATIBILITY" +.PP +The SQL standard includes an +\fBEXECUTE\fR +statement, but it is only for use in embedded SQL\&. This version of the +\fBEXECUTE\fR +statement also uses a somewhat different syntax\&. +.SH "SEE ALSO" +\fBDEALLOCATE\fR(7), \fBPREPARE\fR(7) diff --git a/doc/src/sgml/man7/EXPLAIN.7 b/doc/src/sgml/man7/EXPLAIN.7 new file mode 100644 index 0000000..36b134e --- /dev/null +++ b/doc/src/sgml/man7/EXPLAIN.7 @@ -0,0 +1,421 @@ +'\" t +.\" Title: EXPLAIN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "EXPLAIN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +EXPLAIN \- show the execution plan of a statement +.SH "SYNOPSIS" +.sp +.nf +EXPLAIN [ ( \fIoption\fR [, \&.\&.\&.] ) ] \fIstatement\fR +EXPLAIN [ ANALYZE ] [ VERBOSE ] \fIstatement\fR + +where \fIoption\fR can be one of: + + ANALYZE [ \fIboolean\fR ] + VERBOSE [ \fIboolean\fR ] + COSTS [ \fIboolean\fR ] + SETTINGS [ \fIboolean\fR ] + BUFFERS [ \fIboolean\fR ] + WAL [ \fIboolean\fR ] + TIMING [ \fIboolean\fR ] + SUMMARY [ \fIboolean\fR ] + FORMAT { TEXT | XML | JSON | YAML } +.fi +.SH "DESCRIPTION" +.PP +This command displays the execution plan that the +PostgreSQL +planner generates for the supplied statement\&. The execution plan shows how the table(s) referenced by the statement will be scanned \(em by plain sequential scan, index scan, etc\&. \(em and if multiple tables are referenced, what join algorithms will be used to bring together the required rows from each input table\&. +.PP +The most critical part of the display is the estimated statement execution cost, which is the planner\*(Aqs guess at how long it will take to run the statement (measured in cost units that are arbitrary, but conventionally mean disk page fetches)\&. Actually two numbers are shown: the start\-up cost before the first row can be returned, and the total cost to return all the rows\&. For most queries the total cost is what matters, but in contexts such as a subquery in +EXISTS, the planner will choose the smallest start\-up cost instead of the smallest total cost (since the executor will stop after getting one row, anyway)\&. Also, if you limit the number of rows to return with a +LIMIT +clause, the planner makes an appropriate interpolation between the endpoint costs to estimate which plan is really the cheapest\&. +.PP +The +ANALYZE +option causes the statement to be actually executed, not only planned\&. Then actual run time statistics are added to the display, including the total elapsed time expended within each plan node (in milliseconds) and the total number of rows it actually returned\&. This is useful for seeing whether the planner\*(Aqs estimates are close to reality\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBImportant\fR +.ps -1 +.br +.PP +Keep in mind that the statement is actually executed when the +ANALYZE +option is used\&. Although +\fBEXPLAIN\fR +will discard any output that a +\fBSELECT\fR +would return, other side effects of the statement will happen as usual\&. If you wish to use +\fBEXPLAIN ANALYZE\fR +on an +\fBINSERT\fR, +\fBUPDATE\fR, +\fBDELETE\fR, +\fBMERGE\fR, +\fBCREATE TABLE AS\fR, or +\fBEXECUTE\fR +statement without letting the command affect your data, use this approach: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; +EXPLAIN ANALYZE \&.\&.\&.; +ROLLBACK; +.fi +.if n \{\ +.RE +.\} +.sp .5v +.RE +.PP +Only the +ANALYZE +and +VERBOSE +options can be specified, and only in that order, without surrounding the option list in parentheses\&. Prior to +PostgreSQL +9\&.0, the unparenthesized syntax was the only one supported\&. It is expected that all new options will be supported only in the parenthesized syntax\&. +.SH "PARAMETERS" +.PP +ANALYZE +.RS 4 +Carry out the command and show actual run times and other statistics\&. This parameter defaults to +FALSE\&. +.RE +.PP +VERBOSE +.RS 4 +Display additional information regarding the plan\&. Specifically, include the output column list for each node in the plan tree, schema\-qualify table and function names, always label variables in expressions with their range table alias, and always print the name of each trigger for which statistics are displayed\&. The query identifier will also be displayed if one has been computed, see +compute_query_id +for more details\&. This parameter defaults to +FALSE\&. +.RE +.PP +COSTS +.RS 4 +Include information on the estimated startup and total cost of each plan node, as well as the estimated number of rows and the estimated width of each row\&. This parameter defaults to +TRUE\&. +.RE +.PP +SETTINGS +.RS 4 +Include information on configuration parameters\&. Specifically, include options affecting query planning with value different from the built\-in default value\&. This parameter defaults to +FALSE\&. +.RE +.PP +BUFFERS +.RS 4 +Include information on buffer usage\&. Specifically, include the number of shared blocks hit, read, dirtied, and written, the number of local blocks hit, read, dirtied, and written, the number of temp blocks read and written, and the time spent reading and writing data file blocks and temporary file blocks (in milliseconds) if +track_io_timing +is enabled\&. A +\fIhit\fR +means that a read was avoided because the block was found already in cache when needed\&. Shared blocks contain data from regular tables and indexes; local blocks contain data from temporary tables and indexes; while temporary blocks contain short\-term working data used in sorts, hashes, Materialize plan nodes, and similar cases\&. The number of blocks +\fIdirtied\fR +indicates the number of previously unmodified blocks that were changed by this query; while the number of blocks +\fIwritten\fR +indicates the number of previously\-dirtied blocks evicted from cache by this backend during query processing\&. The number of blocks shown for an upper\-level node includes those used by all its child nodes\&. In text format, only non\-zero values are printed\&. It defaults to +FALSE\&. +.RE +.PP +WAL +.RS 4 +Include information on WAL record generation\&. Specifically, include the number of records, number of full page images (fpi) and the amount of WAL generated in bytes\&. In text format, only non\-zero values are printed\&. This parameter may only be used when +ANALYZE +is also enabled\&. It defaults to +FALSE\&. +.RE +.PP +TIMING +.RS 4 +Include actual startup time and time spent in each node in the output\&. The overhead of repeatedly reading the system clock can slow down the query significantly on some systems, so it may be useful to set this parameter to +FALSE +when only actual row counts, and not exact times, are needed\&. Run time of the entire statement is always measured, even when node\-level timing is turned off with this option\&. This parameter may only be used when +ANALYZE +is also enabled\&. It defaults to +TRUE\&. +.RE +.PP +SUMMARY +.RS 4 +Include summary information (e\&.g\&., totaled timing information) after the query plan\&. Summary information is included by default when +ANALYZE +is used but otherwise is not included by default, but can be enabled using this option\&. Planning time in +\fBEXPLAIN EXECUTE\fR +includes the time required to fetch the plan from the cache and the time required for re\-planning, if necessary\&. +.RE +.PP +FORMAT +.RS 4 +Specify the output format, which can be TEXT, XML, JSON, or YAML\&. Non\-text output contains the same information as the text output format, but is easier for programs to parse\&. This parameter defaults to +TEXT\&. +.RE +.PP +\fIboolean\fR +.RS 4 +Specifies whether the selected option should be turned on or off\&. You can write +TRUE, +ON, or +1 +to enable the option, and +FALSE, +OFF, or +0 +to disable it\&. The +\fIboolean\fR +value can also be omitted, in which case +TRUE +is assumed\&. +.RE +.PP +\fIstatement\fR +.RS 4 +Any +\fBSELECT\fR, +\fBINSERT\fR, +\fBUPDATE\fR, +\fBDELETE\fR, +\fBMERGE\fR, +\fBVALUES\fR, +\fBEXECUTE\fR, +\fBDECLARE\fR, +\fBCREATE TABLE AS\fR, or +\fBCREATE MATERIALIZED VIEW AS\fR +statement, whose execution plan you wish to see\&. +.RE +.SH "OUTPUTS" +.PP +The command\*(Aqs result is a textual description of the plan selected for the +\fIstatement\fR, optionally annotated with execution statistics\&. +Section\ \&14.1 +describes the information provided\&. +.SH "NOTES" +.PP +In order to allow the +PostgreSQL +query planner to make reasonably informed decisions when optimizing queries, the +pg_statistic +data should be up\-to\-date for all tables used in the query\&. Normally the +autovacuum daemon +will take care of that automatically\&. But if a table has recently had substantial changes in its contents, you might need to do a manual +\fBANALYZE\fR +rather than wait for autovacuum to catch up with the changes\&. +.PP +In order to measure the run\-time cost of each node in the execution plan, the current implementation of +\fBEXPLAIN ANALYZE\fR +adds profiling overhead to query execution\&. As a result, running +\fBEXPLAIN ANALYZE\fR +on a query can sometimes take significantly longer than executing the query normally\&. The amount of overhead depends on the nature of the query, as well as the platform being used\&. The worst case occurs for plan nodes that in themselves require very little time per execution, and on machines that have relatively slow operating system calls for obtaining the time of day\&. +.SH "EXAMPLES" +.PP +To show the plan for a simple query on a table with a single +integer +column and 10000 rows: +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN SELECT * FROM foo; + + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Seq Scan on foo (cost=0\&.00\&.\&.155\&.00 rows=10000 width=4) +(1 row) +.fi +.if n \{\ +.RE +.\} +.PP +Here is the same query, with JSON output formatting: +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN (FORMAT JSON) SELECT * FROM foo; + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + [ + + { + + "Plan": { + + "Node Type": "Seq Scan",+ + "Relation Name": "foo", + + "Alias": "foo", + + "Startup Cost": 0\&.00, + + "Total Cost": 155\&.00, + + "Plan Rows": 10000, + + "Plan Width": 4 + + } + + } + + ] +(1 row) +.fi +.if n \{\ +.RE +.\} +.PP +If there is an index and we use a query with an indexable +WHERE +condition, +\fBEXPLAIN\fR +might show a different plan: +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN SELECT * FROM foo WHERE i = 4; + + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Index Scan using fi on foo (cost=0\&.00\&.\&.5\&.98 rows=1 width=4) + Index Cond: (i = 4) +(2 rows) +.fi +.if n \{\ +.RE +.\} +.PP +Here is the same query, but in YAML format: +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN (FORMAT YAML) SELECT * FROM foo WHERE i=\*(Aq4\*(Aq; + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + \- Plan: + + Node Type: "Index Scan" + + Scan Direction: "Forward"+ + Index Name: "fi" + + Relation Name: "foo" + + Alias: "foo" + + Startup Cost: 0\&.00 + + Total Cost: 5\&.98 + + Plan Rows: 1 + + Plan Width: 4 + + Index Cond: "(i = 4)" +(1 row) +.fi +.if n \{\ +.RE +.\} +.sp +XML format is left as an exercise for the reader\&. +.PP +Here is the same plan with cost estimates suppressed: +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN (COSTS FALSE) SELECT * FROM foo WHERE i = 4; + + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Index Scan using fi on foo + Index Cond: (i = 4) +(2 rows) +.fi +.if n \{\ +.RE +.\} +.PP +Here is an example of a query plan for a query using an aggregate function: +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN SELECT sum(i) FROM foo WHERE i < 10; + + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\:\-\- + Aggregate (cost=23\&.93\&.\&.23\&.93 rows=1 width=4) + \-> Index Scan using fi on foo (cost=0\&.00\&.\&.23\&.92 rows=6 width=4) + Index Cond: (i < 10) +(3 rows) +.fi +.if n \{\ +.RE +.\} +.PP +Here is an example of using +\fBEXPLAIN EXECUTE\fR +to display the execution plan for a prepared query: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PREPARE query(int, int) AS SELECT sum(bar) FROM test + WHERE id > $1 AND id < $2 + GROUP BY foo; + +EXPLAIN ANALYZE EXECUTE query(100, 200); + + QUERY PLAN +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\:\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + HashAggregate (cost=9\&.54\&.\&.9\&.54 rows=1 width=8) (actual time=0\&.156\&.\&.0\&.161 rows=11 loops=1) + Group Key: foo + \-> Index Scan using test_pkey on test (cost=0\&.29\&.\&.9\&.29 rows=50 width=8) (actual time=0\&.039\&.\&.0\&.091 rows=99 loops=1) + Index Cond: ((id > $1) AND (id < $2)) + Planning time: 0\&.197 ms + Execution time: 0\&.225 ms +(6 rows) +.fi +.if n \{\ +.RE +.\} +.PP +Of course, the specific numbers shown here depend on the actual contents of the tables involved\&. Also note that the numbers, and even the selected query strategy, might vary between +PostgreSQL +releases due to planner improvements\&. In addition, the +\fBANALYZE\fR +command uses random sampling to estimate data statistics; therefore, it is possible for cost estimates to change after a fresh run of +\fBANALYZE\fR, even if the actual distribution of data in the table has not changed\&. +.SH "COMPATIBILITY" +.PP +There is no +\fBEXPLAIN\fR +statement defined in the SQL standard\&. +.SH "SEE ALSO" +\fBANALYZE\fR(7) diff --git a/doc/src/sgml/man7/FETCH.7 b/doc/src/sgml/man7/FETCH.7 new file mode 100644 index 0000000..6a0f85a --- /dev/null +++ b/doc/src/sgml/man7/FETCH.7 @@ -0,0 +1,352 @@ +'\" t +.\" Title: FETCH +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "FETCH" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +FETCH \- retrieve rows from a query using a cursor +.SH "SYNOPSIS" +.sp +.nf +FETCH [ \fIdirection\fR ] [ FROM | IN ] \fIcursor_name\fR + +where \fIdirection\fR can be one of: + + NEXT + PRIOR + FIRST + LAST + ABSOLUTE \fIcount\fR + RELATIVE \fIcount\fR + \fIcount\fR + ALL + FORWARD + FORWARD \fIcount\fR + FORWARD ALL + BACKWARD + BACKWARD \fIcount\fR + BACKWARD ALL +.fi +.SH "DESCRIPTION" +.PP +\fBFETCH\fR +retrieves rows using a previously\-created cursor\&. +.PP +A cursor has an associated position, which is used by +\fBFETCH\fR\&. The cursor position can be before the first row of the query result, on any particular row of the result, or after the last row of the result\&. When created, a cursor is positioned before the first row\&. After fetching some rows, the cursor is positioned on the row most recently retrieved\&. If +\fBFETCH\fR +runs off the end of the available rows then the cursor is left positioned after the last row, or before the first row if fetching backward\&. +\fBFETCH ALL\fR +or +\fBFETCH BACKWARD ALL\fR +will always leave the cursor positioned after the last row or before the first row\&. +.PP +The forms +NEXT, +PRIOR, +FIRST, +LAST, +ABSOLUTE, +RELATIVE +fetch a single row after moving the cursor appropriately\&. If there is no such row, an empty result is returned, and the cursor is left positioned before the first row or after the last row as appropriate\&. +.PP +The forms using +FORWARD +and +BACKWARD +retrieve the indicated number of rows moving in the forward or backward direction, leaving the cursor positioned on the last\-returned row (or after/before all rows, if the +\fIcount\fR +exceeds the number of rows available)\&. +.PP +RELATIVE 0, +FORWARD 0, and +BACKWARD 0 +all request fetching the current row without moving the cursor, that is, re\-fetching the most recently fetched row\&. This will succeed unless the cursor is positioned before the first row or after the last row; in which case, no row is returned\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +This page describes usage of cursors at the SQL command level\&. If you are trying to use cursors inside a +PL/pgSQL +function, the rules are different \(em see +Section\ \&43.7.3\&. +.sp .5v +.RE +.SH "PARAMETERS" +.PP +\fIdirection\fR +.RS 4 +\fIdirection\fR +defines the fetch direction and number of rows to fetch\&. It can be one of the following: +.PP +NEXT +.RS 4 +Fetch the next row\&. This is the default if +\fIdirection\fR +is omitted\&. +.RE +.PP +PRIOR +.RS 4 +Fetch the prior row\&. +.RE +.PP +FIRST +.RS 4 +Fetch the first row of the query (same as +ABSOLUTE 1)\&. +.RE +.PP +LAST +.RS 4 +Fetch the last row of the query (same as +ABSOLUTE \-1)\&. +.RE +.PP +ABSOLUTE \fIcount\fR +.RS 4 +Fetch the +\fIcount\fR\*(Aqth row of the query, or the +abs(\fIcount\fR)\*(Aqth row from the end if +\fIcount\fR +is negative\&. Position before first row or after last row if +\fIcount\fR +is out of range; in particular, +ABSOLUTE 0 +positions before the first row\&. +.RE +.PP +RELATIVE \fIcount\fR +.RS 4 +Fetch the +\fIcount\fR\*(Aqth succeeding row, or the +abs(\fIcount\fR)\*(Aqth prior row if +\fIcount\fR +is negative\&. +RELATIVE 0 +re\-fetches the current row, if any\&. +.RE +.PP +\fIcount\fR +.RS 4 +Fetch the next +\fIcount\fR +rows (same as +FORWARD \fIcount\fR)\&. +.RE +.PP +ALL +.RS 4 +Fetch all remaining rows (same as +FORWARD ALL)\&. +.RE +.PP +FORWARD +.RS 4 +Fetch the next row (same as +NEXT)\&. +.RE +.PP +FORWARD \fIcount\fR +.RS 4 +Fetch the next +\fIcount\fR +rows\&. +FORWARD 0 +re\-fetches the current row\&. +.RE +.PP +FORWARD ALL +.RS 4 +Fetch all remaining rows\&. +.RE +.PP +BACKWARD +.RS 4 +Fetch the prior row (same as +PRIOR)\&. +.RE +.PP +BACKWARD \fIcount\fR +.RS 4 +Fetch the prior +\fIcount\fR +rows (scanning backwards)\&. +BACKWARD 0 +re\-fetches the current row\&. +.RE +.PP +BACKWARD ALL +.RS 4 +Fetch all prior rows (scanning backwards)\&. +.RE +.RE +.PP +\fIcount\fR +.RS 4 +\fIcount\fR +is a possibly\-signed integer constant, determining the location or number of rows to fetch\&. For +FORWARD +and +BACKWARD +cases, specifying a negative +\fIcount\fR +is equivalent to changing the sense of +FORWARD +and +BACKWARD\&. +.RE +.PP +\fIcursor_name\fR +.RS 4 +An open cursor\*(Aqs name\&. +.RE +.SH "OUTPUTS" +.PP +On successful completion, a +\fBFETCH\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +FETCH \fIcount\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fIcount\fR +is the number of rows fetched (possibly zero)\&. Note that in +psql, the command tag will not actually be displayed, since +psql +displays the fetched rows instead\&. +.SH "NOTES" +.PP +The cursor should be declared with the +SCROLL +option if one intends to use any variants of +\fBFETCH\fR +other than +\fBFETCH NEXT\fR +or +\fBFETCH FORWARD\fR +with a positive count\&. For simple queries +PostgreSQL +will allow backwards fetch from cursors not declared with +SCROLL, but this behavior is best not relied on\&. If the cursor is declared with +NO SCROLL, no backward fetches are allowed\&. +.PP +ABSOLUTE +fetches are not any faster than navigating to the desired row with a relative move: the underlying implementation must traverse all the intermediate rows anyway\&. Negative absolute fetches are even worse: the query must be read to the end to find the last row, and then traversed backward from there\&. However, rewinding to the start of the query (as with +FETCH ABSOLUTE 0) is fast\&. +.PP +\fBDECLARE\fR +is used to define a cursor\&. Use +\fBMOVE\fR +to change cursor position without retrieving data\&. +.SH "EXAMPLES" +.PP +The following example traverses a table using a cursor: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN WORK; + +\-\- Set up a cursor: +DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films; + +\-\- Fetch the first 5 rows in the cursor liahona: +FETCH FORWARD 5 FROM liahona; + + code | title | did | date_prod | kind | len +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- + BL101 | The Third Man | 101 | 1949\-12\-23 | Drama | 01:44 + BL102 | The African Queen | 101 | 1951\-08\-11 | Romantic | 01:43 + JL201 | Une Femme est une Femme | 102 | 1961\-03\-12 | Romantic | 01:25 + P_301 | Vertigo | 103 | 1958\-11\-14 | Action | 02:08 + P_302 | Becket | 103 | 1964\-02\-03 | Drama | 02:28 + +\-\- Fetch the previous row: +FETCH PRIOR FROM liahona; + + code | title | did | date_prod | kind | len +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- + P_301 | Vertigo | 103 | 1958\-11\-14 | Action | 02:08 + +\-\- Close the cursor and end the transaction: +CLOSE liahona; +COMMIT WORK; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The SQL standard defines +\fBFETCH\fR +for use in embedded SQL only\&. The variant of +\fBFETCH\fR +described here returns the data as if it were a +\fBSELECT\fR +result rather than placing it in host variables\&. Other than this point, +\fBFETCH\fR +is fully upward\-compatible with the SQL standard\&. +.PP +The +\fBFETCH\fR +forms involving +FORWARD +and +BACKWARD, as well as the forms +FETCH \fIcount\fR +and +FETCH ALL, in which +FORWARD +is implicit, are +PostgreSQL +extensions\&. +.PP +The SQL standard allows only +FROM +preceding the cursor name; the option to use +IN, or to leave them out altogether, is an extension\&. +.SH "SEE ALSO" +\fBCLOSE\fR(7), \fBDECLARE\fR(7), \fBMOVE\fR(7) diff --git a/doc/src/sgml/man7/GRANT.7 b/doc/src/sgml/man7/GRANT.7 new file mode 100644 index 0000000..08fae60 --- /dev/null +++ b/doc/src/sgml/man7/GRANT.7 @@ -0,0 +1,416 @@ +'\" t +.\" Title: GRANT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "GRANT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +GRANT \- define access privileges +.SH "SYNOPSIS" +.sp +.nf +GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON { [ TABLE ] \fItable_name\fR [, \&.\&.\&.] + | ALL TABLES IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] } + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { { SELECT | INSERT | UPDATE | REFERENCES } ( \fIcolumn_name\fR [, \&.\&.\&.] ) + [, \&.\&.\&.] | ALL [ PRIVILEGES ] ( \fIcolumn_name\fR [, \&.\&.\&.] ) } + ON [ TABLE ] \fItable_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { { USAGE | SELECT | UPDATE } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON { SEQUENCE \fIsequence_name\fR [, \&.\&.\&.] + | ALL SEQUENCES IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] } + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { { CREATE | CONNECT | TEMPORARY | TEMP } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON DATABASE \fIdatabase_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON DOMAIN \fIdomain_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON FOREIGN DATA WRAPPER \fIfdw_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON FOREIGN SERVER \fIserver_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { EXECUTE | ALL [ PRIVILEGES ] } + ON { { FUNCTION | PROCEDURE | ROUTINE } \fIroutine_name\fR [ ( [ [ \fIargmode\fR ] [ \fIarg_name\fR ] \fIarg_type\fR [, \&.\&.\&.] ] ) ] [, \&.\&.\&.] + | ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] } + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON LANGUAGE \fIlang_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { { SELECT | UPDATE } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON LARGE OBJECT \fIloid\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { { SET | ALTER SYSTEM } [, \&.\&.\&. ] | ALL [ PRIVILEGES ] } + ON PARAMETER \fIconfiguration_parameter\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { { CREATE | USAGE } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON SCHEMA \fIschema_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { CREATE | ALL [ PRIVILEGES ] } + ON TABLESPACE \fItablespace_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT { USAGE | ALL [ PRIVILEGES ] } + ON TYPE \fItype_name\fR [, \&.\&.\&.] + TO \fIrole_specification\fR [, \&.\&.\&.] [ WITH GRANT OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +GRANT \fIrole_name\fR [, \&.\&.\&.] TO \fIrole_specification\fR [, \&.\&.\&.] + [ WITH ADMIN OPTION ] + [ GRANTED BY \fIrole_specification\fR ] + +where \fIrole_specification\fR can be: + + [ GROUP ] \fIrole_name\fR + | PUBLIC + | CURRENT_ROLE + | CURRENT_USER + | SESSION_USER +.fi +.SH "DESCRIPTION" +.PP +The +\fBGRANT\fR +command has two basic variants: one that grants privileges on a database object (table, column, view, foreign table, sequence, database, foreign\-data wrapper, foreign server, function, procedure, procedural language, large object, configuration parameter, schema, tablespace, or type), and one that grants membership in a role\&. These variants are similar in many ways, but they are different enough to be described separately\&. +.SS "GRANT on Database Objects" +.PP +This variant of the +\fBGRANT\fR +command gives specific privileges on a database object to one or more roles\&. These privileges are added to those already granted, if any\&. +.PP +The key word +PUBLIC +indicates that the privileges are to be granted to all roles, including those that might be created later\&. +PUBLIC +can be thought of as an implicitly defined group that always includes all roles\&. Any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to +PUBLIC\&. +.PP +If +WITH GRANT OPTION +is specified, the recipient of the privilege can in turn grant it to others\&. Without a grant option, the recipient cannot do that\&. Grant options cannot be granted to +PUBLIC\&. +.PP +If +GRANTED BY +is specified, the specified grantor must be the current user\&. This clause is currently present in this form only for SQL compatibility\&. +.PP +There is no need to grant privileges to the owner of an object (usually the user that created it), as the owner has all privileges by default\&. (The owner could, however, choose to revoke some of their own privileges for safety\&.) +.PP +The right to drop an object, or to alter its definition in any way, is not treated as a grantable privilege; it is inherent in the owner, and cannot be granted or revoked\&. (However, a similar effect can be obtained by granting or revoking membership in the role that owns the object; see below\&.) The owner implicitly has all grant options for the object, too\&. +.PP +The possible privileges are: +.PP +SELECT +.br +INSERT +.br +UPDATE +.br +DELETE +.br +TRUNCATE +.br +REFERENCES +.br +TRIGGER +.br +CREATE +.br +CONNECT +.br +TEMPORARY +.br +EXECUTE +.br +USAGE +.br +SET +.br +ALTER SYSTEM +.RS 4 +Specific types of privileges, as defined in +Section\ \&5.7\&. +.RE +.PP +TEMP +.RS 4 +Alternative spelling for +TEMPORARY\&. +.RE +.PP +ALL PRIVILEGES +.RS 4 +Grant all of the privileges available for the object\*(Aqs type\&. The +PRIVILEGES +key word is optional in +PostgreSQL, though it is required by strict SQL\&. +.RE +.PP +The +FUNCTION +syntax works for plain functions, aggregate functions, and window functions, but not for procedures; use +PROCEDURE +for those\&. Alternatively, use +ROUTINE +to refer to a function, aggregate function, window function, or procedure regardless of its precise type\&. +.PP +There is also an option to grant privileges on all objects of the same type within one or more schemas\&. This functionality is currently supported only for tables, sequences, functions, and procedures\&. +ALL TABLES +also affects views and foreign tables, just like the specific\-object +\fBGRANT\fR +command\&. +ALL FUNCTIONS +also affects aggregate and window functions, but not procedures, again just like the specific\-object +\fBGRANT\fR +command\&. Use +ALL ROUTINES +to include procedures\&. +.SS "GRANT on Roles" +.PP +This variant of the +\fBGRANT\fR +command grants membership in a role to one or more other roles\&. Membership in a role is significant because it conveys the privileges granted to a role to each of its members\&. +.PP +If +WITH ADMIN OPTION +is specified, the member can in turn grant membership in the role to others, and revoke membership in the role as well\&. Without the admin option, ordinary users cannot do that\&. A role is not considered to hold +WITH ADMIN OPTION +on itself\&. Database superusers can grant or revoke membership in any role to anyone\&. Roles having +CREATEROLE +privilege can grant or revoke membership in any role that is not a superuser\&. +.PP +If +GRANTED BY +is specified, the grant is recorded as having been done by the specified role\&. Only database superusers may use this option, except when it names the same role executing the command\&. +.PP +Unlike the case with privileges, membership in a role cannot be granted to +PUBLIC\&. Note also that this form of the command does not allow the noise word +GROUP +in +\fIrole_specification\fR\&. +.SH "NOTES" +.PP +The +\fBREVOKE\fR +command is used to revoke access privileges\&. +.PP +Since +PostgreSQL +8\&.1, the concepts of users and groups have been unified into a single kind of entity called a role\&. It is therefore no longer necessary to use the keyword +GROUP +to identify whether a grantee is a user or a group\&. +GROUP +is still allowed in the command, but it is a noise word\&. +.PP +A user may perform +\fBSELECT\fR, +\fBINSERT\fR, etc\&. on a column if they hold that privilege for either the specific column or its whole table\&. Granting the privilege at the table level and then revoking it for one column will not do what one might wish: the table\-level grant is unaffected by a column\-level operation\&. +.PP +When a non\-owner of an object attempts to +\fBGRANT\fR +privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object\&. As long as some privilege is available, the command will proceed, but it will grant only those privileges for which the user has grant options\&. The +\fBGRANT ALL PRIVILEGES\fR +forms will issue a warning message if no grant options are held, while the other forms will issue a warning if grant options for any of the privileges specifically named in the command are not held\&. (In principle these statements apply to the object owner as well, but since the owner is always treated as holding all grant options, the cases can never occur\&.) +.PP +It should be noted that database superusers can access all objects regardless of object privilege settings\&. This is comparable to the rights of +root +in a Unix system\&. As with +root, it\*(Aqs unwise to operate as a superuser except when absolutely necessary\&. +.PP +If a superuser chooses to issue a +\fBGRANT\fR +or +\fBREVOKE\fR +command, the command is performed as though it were issued by the owner of the affected object\&. In particular, privileges granted via such a command will appear to have been granted by the object owner\&. (For role membership, the membership appears to have been granted by the containing role itself\&.) +.PP +\fBGRANT\fR +and +\fBREVOKE\fR +can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges +WITH GRANT OPTION +on the object\&. In this case the privileges will be recorded as having been granted by the role that actually owns the object or holds the privileges +WITH GRANT OPTION\&. For example, if table +t1 +is owned by role +g1, of which role +u1 +is a member, then +u1 +can grant privileges on +t1 +to +u2, but those privileges will appear to have been granted directly by +g1\&. Any other member of role +g1 +could revoke them later\&. +.PP +If the role executing +\fBGRANT\fR +holds the required privileges indirectly via more than one role membership path, it is unspecified which containing role will be recorded as having done the grant\&. In such cases it is best practice to use +\fBSET ROLE\fR +to become the specific role you want to do the +\fBGRANT\fR +as\&. +.PP +Granting permission on a table does not automatically extend permissions to any sequences used by the table, including sequences tied to +SERIAL +columns\&. Permissions on sequences must be set separately\&. +.PP +See +Section\ \&5.7 +for more information about specific privilege types, as well as how to inspect objects\*(Aq privileges\&. +.SH "EXAMPLES" +.PP +Grant insert privilege to all users on table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +GRANT INSERT ON films TO PUBLIC; +.fi +.if n \{\ +.RE +.\} +.PP +Grant all available privileges to user +manuel +on view +kinds: +.sp +.if n \{\ +.RS 4 +.\} +.nf +GRANT ALL PRIVILEGES ON kinds TO manuel; +.fi +.if n \{\ +.RE +.\} +.sp +Note that while the above will indeed grant all privileges if executed by a superuser or the owner of +kinds, when executed by someone else it will only grant those permissions for which the someone else has grant options\&. +.PP +Grant membership in role +admins +to user +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +GRANT admins TO joe; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +According to the SQL standard, the +PRIVILEGES +key word in +ALL PRIVILEGES +is required\&. The SQL standard does not support setting the privileges on more than one object per command\&. +.PP +PostgreSQL +allows an object owner to revoke their own ordinary privileges: for example, a table owner can make the table read\-only to themselves by revoking their own +INSERT, +UPDATE, +DELETE, and +TRUNCATE +privileges\&. This is not possible according to the SQL standard\&. The reason is that +PostgreSQL +treats the owner\*(Aqs privileges as having been granted by the owner to themselves; therefore they can revoke them too\&. In the SQL standard, the owner\*(Aqs privileges are granted by an assumed entity +\(lq_SYSTEM\(rq\&. Not being +\(lq_SYSTEM\(rq, the owner cannot revoke these rights\&. +.PP +According to the SQL standard, grant options can be granted to +PUBLIC; PostgreSQL only supports granting grant options to roles\&. +.PP +The SQL standard allows the +GRANTED BY +option to specify only +CURRENT_USER +or +CURRENT_ROLE\&. The other variants are PostgreSQL extensions\&. +.PP +The SQL standard provides for a +USAGE +privilege on other kinds of objects: character sets, collations, translations\&. +.PP +In the SQL standard, sequences only have a +USAGE +privilege, which controls the use of the +NEXT VALUE FOR +expression, which is equivalent to the function +\fBnextval\fR +in PostgreSQL\&. The sequence privileges +SELECT +and +UPDATE +are PostgreSQL extensions\&. The application of the sequence +USAGE +privilege to the +currval +function is also a PostgreSQL extension (as is the function itself)\&. +.PP +Privileges on databases, tablespaces, schemas, languages, and configuration parameters are +PostgreSQL +extensions\&. +.SH "SEE ALSO" +\fBREVOKE\fR(7), ALTER DEFAULT PRIVILEGES (\fBALTER_DEFAULT_PRIVILEGES\fR(7)) diff --git a/doc/src/sgml/man7/IMPORT_FOREIGN_SCHEMA.7 b/doc/src/sgml/man7/IMPORT_FOREIGN_SCHEMA.7 new file mode 100644 index 0000000..aa9e50c --- /dev/null +++ b/doc/src/sgml/man7/IMPORT_FOREIGN_SCHEMA.7 @@ -0,0 +1,132 @@ +'\" t +.\" Title: IMPORT FOREIGN SCHEMA +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "IMPORT FOREIGN SCHEMA" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +IMPORT_FOREIGN_SCHEMA \- import table definitions from a foreign server +.SH "SYNOPSIS" +.sp +.nf +IMPORT FOREIGN SCHEMA \fIremote_schema\fR + [ { LIMIT TO | EXCEPT } ( \fItable_name\fR [, \&.\&.\&.] ) ] + FROM SERVER \fIserver_name\fR + INTO \fIlocal_schema\fR + [ OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&. ] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBIMPORT FOREIGN SCHEMA\fR +creates foreign tables that represent tables existing on a foreign server\&. The new foreign tables will be owned by the user issuing the command and are created with the correct column definitions and options to match the remote tables\&. +.PP +By default, all tables and views existing in a particular schema on the foreign server are imported\&. Optionally, the list of tables can be limited to a specified subset, or specific tables can be excluded\&. The new foreign tables are all created in the target schema, which must already exist\&. +.PP +To use +\fBIMPORT FOREIGN SCHEMA\fR, the user must have +USAGE +privilege on the foreign server, as well as +CREATE +privilege on the target schema\&. +.SH "PARAMETERS" +.PP +\fIremote_schema\fR +.RS 4 +The remote schema to import from\&. The specific meaning of a remote schema depends on the foreign data wrapper in use\&. +.RE +.PP +LIMIT TO ( \fItable_name\fR [, \&.\&.\&.] ) +.RS 4 +Import only foreign tables matching one of the given table names\&. Other tables existing in the foreign schema will be ignored\&. +.RE +.PP +EXCEPT ( \fItable_name\fR [, \&.\&.\&.] ) +.RS 4 +Exclude specified foreign tables from the import\&. All tables existing in the foreign schema will be imported except the ones listed here\&. +.RE +.PP +\fIserver_name\fR +.RS 4 +The foreign server to import from\&. +.RE +.PP +\fIlocal_schema\fR +.RS 4 +The schema in which the imported foreign tables will be created\&. +.RE +.PP +OPTIONS ( \fIoption\fR \*(Aq\fIvalue\fR\*(Aq [, \&.\&.\&.] ) +.RS 4 +Options to be used during the import\&. The allowed option names and values are specific to each foreign data wrapper\&. +.RE +.SH "EXAMPLES" +.PP +Import table definitions from a remote schema +foreign_films +on server +film_server, creating the foreign tables in local schema +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +IMPORT FOREIGN SCHEMA foreign_films + FROM SERVER film_server INTO films; +.fi +.if n \{\ +.RE +.\} +.PP +As above, but import only the two tables +actors +and +directors +(if they exist): +.sp +.if n \{\ +.RS 4 +.\} +.nf +IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors) + FROM SERVER film_server INTO films; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBIMPORT FOREIGN SCHEMA\fR +command conforms to the +SQL +standard, except that the +OPTIONS +clause is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7)), CREATE SERVER (\fBCREATE_SERVER\fR(7)) diff --git a/doc/src/sgml/man7/INSERT.7 b/doc/src/sgml/man7/INSERT.7 new file mode 100644 index 0000000..a88ba0f --- /dev/null +++ b/doc/src/sgml/man7/INSERT.7 @@ -0,0 +1,766 @@ +'\" t +.\" Title: INSERT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "INSERT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +INSERT \- create new rows in a table +.SH "SYNOPSIS" +.sp +.nf +[ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ] +INSERT INTO \fItable_name\fR [ AS \fIalias\fR ] [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] + [ OVERRIDING { SYSTEM | USER } VALUE ] + { DEFAULT VALUES | VALUES ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) [, \&.\&.\&.] | \fIquery\fR } + [ ON CONFLICT [ \fIconflict_target\fR ] \fIconflict_action\fR ] + [ RETURNING * | \fIoutput_expression\fR [ [ AS ] \fIoutput_name\fR ] [, \&.\&.\&.] ] + +where \fIconflict_target\fR can be one of: + + ( { \fIindex_column_name\fR | ( \fIindex_expression\fR ) } [ COLLATE \fIcollation\fR ] [ \fIopclass\fR ] [, \&.\&.\&.] ) [ WHERE \fIindex_predicate\fR ] + ON CONSTRAINT \fIconstraint_name\fR + +and \fIconflict_action\fR is one of: + + DO NOTHING + DO UPDATE SET { \fIcolumn_name\fR = { \fIexpression\fR | DEFAULT } | + ( \fIcolumn_name\fR [, \&.\&.\&.] ) = [ ROW ] ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) | + ( \fIcolumn_name\fR [, \&.\&.\&.] ) = ( \fIsub\-SELECT\fR ) + } [, \&.\&.\&.] + [ WHERE \fIcondition\fR ] +.fi +.SH "DESCRIPTION" +.PP +\fBINSERT\fR +inserts new rows into a table\&. One can insert one or more rows specified by value expressions, or zero or more rows resulting from a query\&. +.PP +The target column names can be listed in any order\&. If no list of column names is given at all, the default is all the columns of the table in their declared order; or the first +\fIN\fR +column names, if there are only +\fIN\fR +columns supplied by the +VALUES +clause or +\fIquery\fR\&. The values supplied by the +VALUES +clause or +\fIquery\fR +are associated with the explicit or implicit column list left\-to\-right\&. +.PP +Each column not present in the explicit or implicit column list will be filled with a default value, either its declared default value or null if there is none\&. +.PP +If the expression for any column is not of the correct data type, automatic type conversion will be attempted\&. +.PP +\fBINSERT\fR +into tables that lack unique indexes will not be blocked by concurrent activity\&. Tables with unique indexes might block if concurrent sessions perform actions that lock or modify rows matching the unique index values being inserted; the details are covered in +Section\ \&64.5\&. +ON CONFLICT +can be used to specify an alternative action to raising a unique constraint or exclusion constraint violation error\&. (See +ON CONFLICT Clause +below\&.) +.PP +The optional +RETURNING +clause causes +\fBINSERT\fR +to compute and return value(s) based on each row actually inserted (or updated, if an +ON CONFLICT DO UPDATE +clause was used)\&. This is primarily useful for obtaining values that were supplied by defaults, such as a serial sequence number\&. However, any expression using the table\*(Aqs columns is allowed\&. The syntax of the +RETURNING +list is identical to that of the output list of +\fBSELECT\fR\&. Only rows that were successfully inserted or updated will be returned\&. For example, if a row was locked but not updated because an +ON CONFLICT DO UPDATE \&.\&.\&. WHERE +clause +\fIcondition\fR +was not satisfied, the row will not be returned\&. +.PP +You must have +INSERT +privilege on a table in order to insert into it\&. If +ON CONFLICT DO UPDATE +is present, +UPDATE +privilege on the table is also required\&. +.PP +If a column list is specified, you only need +INSERT +privilege on the listed columns\&. Similarly, when +ON CONFLICT DO UPDATE +is specified, you only need +UPDATE +privilege on the column(s) that are listed to be updated\&. However, +ON CONFLICT DO UPDATE +also requires +SELECT +privilege on any column whose values are read in the +ON CONFLICT DO UPDATE +expressions or +\fIcondition\fR\&. +.PP +Use of the +RETURNING +clause requires +SELECT +privilege on all columns mentioned in +RETURNING\&. If you use the +\fIquery\fR +clause to insert rows from a query, you of course need to have +SELECT +privilege on any table or column used in the query\&. +.SH "PARAMETERS" +.SS "Inserting" +.PP +This section covers parameters that may be used when only inserting new rows\&. Parameters +\fIexclusively\fR +used with the +ON CONFLICT +clause are described separately\&. +.PP +\fIwith_query\fR +.RS 4 +The +WITH +clause allows you to specify one or more subqueries that can be referenced by name in the +\fBINSERT\fR +query\&. See +Section\ \&7.8 +and +\fBSELECT\fR(7) +for details\&. +.sp +It is possible for the +\fIquery\fR +(\fBSELECT\fR +statement) to also contain a +WITH +clause\&. In such a case both sets of +\fIwith_query\fR +can be referenced within the +\fIquery\fR, but the second one takes precedence since it is more closely nested\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of an existing table\&. +.RE +.PP +\fIalias\fR +.RS 4 +A substitute name for +\fItable_name\fR\&. When an alias is provided, it completely hides the actual name of the table\&. This is particularly useful when +ON CONFLICT DO UPDATE +targets a table named +\fIexcluded\fR, since that will otherwise be taken as the name of the special table representing the row proposed for insertion\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column in the table named by +\fItable_name\fR\&. The column name can be qualified with a subfield name or array subscript, if needed\&. (Inserting into only some fields of a composite column leaves the other fields null\&.) When referencing a column with +ON CONFLICT DO UPDATE, do not include the table\*(Aqs name in the specification of a target column\&. For example, +INSERT INTO table_name \&.\&.\&. ON CONFLICT DO UPDATE SET table_name\&.col = 1 +is invalid (this follows the general behavior for +\fBUPDATE\fR)\&. +.RE +.PP +OVERRIDING SYSTEM VALUE +.RS 4 +If this clause is specified, then any values supplied for identity columns will override the default sequence\-generated values\&. +.sp +For an identity column defined as +GENERATED ALWAYS, it is an error to insert an explicit value (other than +DEFAULT) without specifying either +OVERRIDING SYSTEM VALUE +or +OVERRIDING USER VALUE\&. (For an identity column defined as +GENERATED BY DEFAULT, +OVERRIDING SYSTEM VALUE +is the normal behavior and specifying it does nothing, but +PostgreSQL +allows it as an extension\&.) +.RE +.PP +OVERRIDING USER VALUE +.RS 4 +If this clause is specified, then any values supplied for identity columns are ignored and the default sequence\-generated values are applied\&. +.sp +This clause is useful for example when copying values between tables\&. Writing +INSERT INTO tbl2 OVERRIDING USER VALUE SELECT * FROM tbl1 +will copy from +tbl1 +all columns that are not identity columns in +tbl2 +while values for the identity columns in +tbl2 +will be generated by the sequences associated with +tbl2\&. +.RE +.PP +DEFAULT VALUES +.RS 4 +All columns will be filled with their default values, as if +DEFAULT +were explicitly specified for each column\&. (An +OVERRIDING +clause is not permitted in this form\&.) +.RE +.PP +\fIexpression\fR +.RS 4 +An expression or value to assign to the corresponding column\&. +.RE +.PP +DEFAULT +.RS 4 +The corresponding column will be filled with its default value\&. An identity column will be filled with a new value generated by the associated sequence\&. For a generated column, specifying this is permitted but merely specifies the normal behavior of computing the column from its generation expression\&. +.RE +.PP +\fIquery\fR +.RS 4 +A query (\fBSELECT\fR +statement) that supplies the rows to be inserted\&. Refer to the +\fBSELECT\fR(7) +statement for a description of the syntax\&. +.RE +.PP +\fIoutput_expression\fR +.RS 4 +An expression to be computed and returned by the +\fBINSERT\fR +command after each row is inserted or updated\&. The expression can use any column names of the table named by +\fItable_name\fR\&. Write +* +to return all columns of the inserted or updated row(s)\&. +.RE +.PP +\fIoutput_name\fR +.RS 4 +A name to use for a returned column\&. +.RE +.SS "ON CONFLICT Clause" +.PP +The optional +ON CONFLICT +clause specifies an alternative action to raising a unique violation or exclusion constraint violation error\&. For each individual row proposed for insertion, either the insertion proceeds, or, if an +\fIarbiter\fR +constraint or index specified by +\fIconflict_target\fR +is violated, the alternative +\fIconflict_action\fR +is taken\&. +ON CONFLICT DO NOTHING +simply avoids inserting a row as its alternative action\&. +ON CONFLICT DO UPDATE +updates the existing row that conflicts with the row proposed for insertion as its alternative action\&. +.PP +\fIconflict_target\fR +can perform +\fIunique index inference\fR\&. When performing inference, it consists of one or more +\fIindex_column_name\fR +columns and/or +\fIindex_expression\fR +expressions, and an optional +\fIindex_predicate\fR\&. All +\fItable_name\fR +unique indexes that, without regard to order, contain exactly the +\fIconflict_target\fR\-specified columns/expressions are inferred (chosen) as arbiter indexes\&. If an +\fIindex_predicate\fR +is specified, it must, as a further requirement for inference, satisfy arbiter indexes\&. Note that this means a non\-partial unique index (a unique index without a predicate) will be inferred (and thus used by +ON CONFLICT) if such an index satisfying every other criteria is available\&. If an attempt at inference is unsuccessful, an error is raised\&. +.PP +ON CONFLICT DO UPDATE +guarantees an atomic +\fBINSERT\fR +or +\fBUPDATE\fR +outcome; provided there is no independent error, one of those two outcomes is guaranteed, even under high concurrency\&. This is also known as +UPSERT +\(em +\(lqUPDATE or INSERT\(rq\&. +.PP +\fIconflict_target\fR +.RS 4 +Specifies which conflicts +ON CONFLICT +takes the alternative action on by choosing +arbiter indexes\&. Either performs +\fIunique index inference\fR, or names a constraint explicitly\&. For +ON CONFLICT DO NOTHING, it is optional to specify a +\fIconflict_target\fR; when omitted, conflicts with all usable constraints (and unique indexes) are handled\&. For +ON CONFLICT DO UPDATE, a +\fIconflict_target\fR +\fImust\fR +be provided\&. +.RE +.PP +\fIconflict_action\fR +.RS 4 +\fIconflict_action\fR +specifies an alternative +ON CONFLICT +action\&. It can be either +DO NOTHING, or a +DO UPDATE +clause specifying the exact details of the +UPDATE +action to be performed in case of a conflict\&. The +SET +and +WHERE +clauses in +ON CONFLICT DO UPDATE +have access to the existing row using the table\*(Aqs name (or an alias), and to the row proposed for insertion using the special +\fIexcluded\fR +table\&. +SELECT +privilege is required on any column in the target table where corresponding +\fIexcluded\fR +columns are read\&. +.sp +Note that the effects of all per\-row +BEFORE INSERT +triggers are reflected in +\fIexcluded\fR +values, since those effects may have contributed to the row being excluded from insertion\&. +.RE +.PP +\fIindex_column_name\fR +.RS 4 +The name of a +\fItable_name\fR +column\&. Used to infer arbiter indexes\&. Follows +\fBCREATE INDEX\fR +format\&. +SELECT +privilege on +\fIindex_column_name\fR +is required\&. +.RE +.PP +\fIindex_expression\fR +.RS 4 +Similar to +\fIindex_column_name\fR, but used to infer expressions on +\fItable_name\fR +columns appearing within index definitions (not simple columns)\&. Follows +\fBCREATE INDEX\fR +format\&. +SELECT +privilege on any column appearing within +\fIindex_expression\fR +is required\&. +.RE +.PP +\fIcollation\fR +.RS 4 +When specified, mandates that corresponding +\fIindex_column_name\fR +or +\fIindex_expression\fR +use a particular collation in order to be matched during inference\&. Typically this is omitted, as collations usually do not affect whether or not a constraint violation occurs\&. Follows +\fBCREATE INDEX\fR +format\&. +.RE +.PP +\fIopclass\fR +.RS 4 +When specified, mandates that corresponding +\fIindex_column_name\fR +or +\fIindex_expression\fR +use particular operator class in order to be matched during inference\&. Typically this is omitted, as the +\fIequality\fR +semantics are often equivalent across a type\*(Aqs operator classes anyway, or because it\*(Aqs sufficient to trust that the defined unique indexes have the pertinent definition of equality\&. Follows +\fBCREATE INDEX\fR +format\&. +.RE +.PP +\fIindex_predicate\fR +.RS 4 +Used to allow inference of partial unique indexes\&. Any indexes that satisfy the predicate (which need not actually be partial indexes) can be inferred\&. Follows +\fBCREATE INDEX\fR +format\&. +SELECT +privilege on any column appearing within +\fIindex_predicate\fR +is required\&. +.RE +.PP +\fIconstraint_name\fR +.RS 4 +Explicitly specifies an arbiter +\fIconstraint\fR +by name, rather than inferring a constraint or index\&. +.RE +.PP +\fIcondition\fR +.RS 4 +An expression that returns a value of type +boolean\&. Only rows for which this expression returns +true +will be updated, although all rows will be locked when the +ON CONFLICT DO UPDATE +action is taken\&. Note that +\fIcondition\fR +is evaluated last, after a conflict has been identified as a candidate to update\&. +.RE +.PP +Note that exclusion constraints are not supported as arbiters with +ON CONFLICT DO UPDATE\&. In all cases, only +NOT DEFERRABLE +constraints and unique indexes are supported as arbiters\&. +.PP +\fBINSERT\fR +with an +ON CONFLICT DO UPDATE +clause is a +\(lqdeterministic\(rq +statement\&. This means that the command will not be allowed to affect any single existing row more than once; a cardinality violation error will be raised when this situation arises\&. Rows proposed for insertion should not duplicate each other in terms of attributes constrained by an arbiter index or constraint\&. +.PP +Note that it is currently not supported for the +ON CONFLICT DO UPDATE +clause of an +\fBINSERT\fR +applied to a partitioned table to update the partition key of a conflicting row such that it requires the row be moved to a new partition\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +.PP +It is often preferable to use unique index inference rather than naming a constraint directly using +ON CONFLICT ON CONSTRAINT +\fI constraint_name\fR\&. Inference will continue to work correctly when the underlying index is replaced by another more or less equivalent index in an overlapping way, for example when using +CREATE UNIQUE INDEX \&.\&.\&. CONCURRENTLY +before dropping the index being replaced\&. +.sp .5v +.RE +.SH "OUTPUTS" +.PP +On successful completion, an +\fBINSERT\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT \fIoid\fR \fIcount\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fIcount\fR +is the number of rows inserted or updated\&. +\fIoid\fR +is always 0 (it used to be the +OID +assigned to the inserted row if +\fIcount\fR +was exactly one and the target table was declared +WITH OIDS +and 0 otherwise, but creating a table +WITH OIDS +is not supported anymore)\&. +.PP +If the +\fBINSERT\fR +command contains a +RETURNING +clause, the result will be similar to that of a +\fBSELECT\fR +statement containing the columns and values defined in the +RETURNING +list, computed over the row(s) inserted or updated by the command\&. +.SH "NOTES" +.PP +If the specified table is a partitioned table, each row is routed to the appropriate partition and inserted into it\&. If the specified table is a partition, an error will occur if one of the input rows violates the partition constraint\&. +.PP +You may also wish to consider using +\fBMERGE\fR, since that allows mixing +\fBINSERT\fR, +\fBUPDATE\fR, and +\fBDELETE\fR +within a single statement\&. See +\fBMERGE\fR(7)\&. +.SH "EXAMPLES" +.PP +Insert a single row into table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films VALUES + (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, \*(Aq1971\-07\-13\*(Aq, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +In this example, the +len +column is omitted and therefore it will have the default value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films (code, title, did, date_prod, kind) + VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, \*(Aq1961\-06\-16\*(Aq, \*(AqDrama\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +This example uses the +DEFAULT +clause for the date columns rather than specifying a value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films VALUES + (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, DEFAULT, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq); +INSERT INTO films (code, title, did, date_prod, kind) + VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, DEFAULT, \*(AqDrama\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +To insert a row consisting entirely of default values: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films DEFAULT VALUES; +.fi +.if n \{\ +.RE +.\} +.PP +To insert multiple rows using the multirow +\fBVALUES\fR +syntax: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films (code, title, did, date_prod, kind) VALUES + (\*(AqB6717\*(Aq, \*(AqTampopo\*(Aq, 110, \*(Aq1985\-02\-10\*(Aq, \*(AqComedy\*(Aq), + (\*(AqHG120\*(Aq, \*(AqThe Dinner Game\*(Aq, 140, DEFAULT, \*(AqComedy\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +This example inserts some rows into table +films +from a table +tmp_films +with the same column layout as +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films SELECT * FROM tmp_films WHERE date_prod < \*(Aq2004\-05\-07\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +This example inserts into array columns: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\-\- Create an empty 3x3 gameboard for noughts\-and\-crosses +INSERT INTO tictactoe (game, board[1:3][1:3]) + VALUES (1, \*(Aq{{" "," "," "},{" "," "," "},{" "," "," "}}\*(Aq); +\-\- The subscripts in the above example aren\*(Aqt really needed +INSERT INTO tictactoe (game, board) + VALUES (2, \*(Aq{{X," "," "},{" ",O," "},{" ",X," "}}\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Insert a single row into table +distributors, returning the sequence number generated by the +DEFAULT +clause: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO distributors (did, dname) VALUES (DEFAULT, \*(AqXYZ Widgets\*(Aq) + RETURNING did; +.fi +.if n \{\ +.RE +.\} +.PP +Increment the sales count of the salesperson who manages the account for Acme Corporation, and record the whole updated row along with current time in a log table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +WITH upd AS ( + UPDATE employees SET sales_count = sales_count + 1 WHERE id = + (SELECT sales_person FROM accounts WHERE name = \*(AqAcme Corporation\*(Aq) + RETURNING * +) +INSERT INTO employees_log SELECT *, current_timestamp FROM upd; +.fi +.if n \{\ +.RE +.\} +.PP +Insert or update new distributors as appropriate\&. Assumes a unique index has been defined that constrains values appearing in the +did +column\&. Note that the special +\fIexcluded\fR +table is used to reference values originally proposed for insertion: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO distributors (did, dname) + VALUES (5, \*(AqGizmo Transglobal\*(Aq), (6, \*(AqAssociated Computing, Inc\*(Aq) + ON CONFLICT (did) DO UPDATE SET dname = EXCLUDED\&.dname; +.fi +.if n \{\ +.RE +.\} +.PP +Insert a distributor, or do nothing for rows proposed for insertion when an existing, excluded row (a row with a matching constrained column or columns after before row insert triggers fire) exists\&. Example assumes a unique index has been defined that constrains values appearing in the +did +column: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO distributors (did, dname) VALUES (7, \*(AqRedline GmbH\*(Aq) + ON CONFLICT (did) DO NOTHING; +.fi +.if n \{\ +.RE +.\} +.PP +Insert or update new distributors as appropriate\&. Example assumes a unique index has been defined that constrains values appearing in the +did +column\&. +WHERE +clause is used to limit the rows actually updated (any existing row not updated will still be locked, though): +.sp +.if n \{\ +.RS 4 +.\} +.nf +\-\- Don\*(Aqt update existing distributors based in a certain ZIP code +INSERT INTO distributors AS d (did, dname) VALUES (8, \*(AqAnvil Distribution\*(Aq) + ON CONFLICT (did) DO UPDATE + SET dname = EXCLUDED\&.dname || \*(Aq (formerly \*(Aq || d\&.dname || \*(Aq)\*(Aq + WHERE d\&.zipcode <> \*(Aq21201\*(Aq; + +\-\- Name a constraint directly in the statement (uses associated +\-\- index to arbitrate taking the DO NOTHING action) +INSERT INTO distributors (did, dname) VALUES (9, \*(AqAntwerp Design\*(Aq) + ON CONFLICT ON CONSTRAINT distributors_pkey DO NOTHING; +.fi +.if n \{\ +.RE +.\} +.PP +Insert new distributor if possible; otherwise +DO NOTHING\&. Example assumes a unique index has been defined that constrains values appearing in the +did +column on a subset of rows where the +is_active +Boolean column evaluates to +true: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\-\- This statement could infer a partial unique index on "did" +\-\- with a predicate of "WHERE is_active", but it could also +\-\- just use a regular unique constraint on "did" +INSERT INTO distributors (did, dname) VALUES (10, \*(AqConrad International\*(Aq) + ON CONFLICT (did) WHERE is_active DO NOTHING; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBINSERT\fR +conforms to the SQL standard, except that the +RETURNING +clause is a +PostgreSQL +extension, as is the ability to use +WITH +with +\fBINSERT\fR, and the ability to specify an alternative action with +ON CONFLICT\&. Also, the case in which a column name list is omitted, but not all the columns are filled from the +VALUES +clause or +\fIquery\fR, is disallowed by the standard\&. If you prefer a more SQL standard conforming statement than +ON CONFLICT, see +\fBMERGE\fR(7)\&. +.PP +The SQL standard specifies that +OVERRIDING SYSTEM VALUE +can only be specified if an identity column that is generated always exists\&. PostgreSQL allows the clause in any case and ignores it if it is not applicable\&. +.PP +Possible limitations of the +\fIquery\fR +clause are documented under +\fBSELECT\fR(7)\&. diff --git a/doc/src/sgml/man7/LISTEN.7 b/doc/src/sgml/man7/LISTEN.7 new file mode 100644 index 0000000..dd45c02 --- /dev/null +++ b/doc/src/sgml/man7/LISTEN.7 @@ -0,0 +1,117 @@ +'\" t +.\" Title: LISTEN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "LISTEN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +LISTEN \- listen for a notification +.SH "SYNOPSIS" +.sp +.nf +LISTEN \fIchannel\fR +.fi +.SH "DESCRIPTION" +.PP +\fBLISTEN\fR +registers the current session as a listener on the notification channel named +\fIchannel\fR\&. If the current session is already registered as a listener for this notification channel, nothing is done\&. +.PP +Whenever the command +\fBNOTIFY \fR\fB\fIchannel\fR\fR +is invoked, either by this session or another one connected to the same database, all the sessions currently listening on that notification channel are notified, and each will in turn notify its connected client application\&. +.PP +A session can be unregistered for a given notification channel with the +\fBUNLISTEN\fR +command\&. A session\*(Aqs listen registrations are automatically cleared when the session ends\&. +.PP +The method a client application must use to detect notification events depends on which +PostgreSQL +application programming interface it uses\&. With the +libpq +library, the application issues +\fBLISTEN\fR +as an ordinary SQL command, and then must periodically call the function +\fBPQnotifies\fR +to find out whether any notification events have been received\&. Other interfaces such as +libpgtcl +provide higher\-level methods for handling notify events; indeed, with +libpgtcl +the application programmer should not even issue +\fBLISTEN\fR +or +\fBUNLISTEN\fR +directly\&. See the documentation for the interface you are using for more details\&. +.SH "PARAMETERS" +.PP +\fIchannel\fR +.RS 4 +Name of a notification channel (any identifier)\&. +.RE +.SH "NOTES" +.PP +\fBLISTEN\fR +takes effect at transaction commit\&. If +\fBLISTEN\fR +or +\fBUNLISTEN\fR +is executed within a transaction that later rolls back, the set of notification channels being listened to is unchanged\&. +.PP +A transaction that has executed +\fBLISTEN\fR +cannot be prepared for two\-phase commit\&. +.PP +There is a race condition when first setting up a listening session: if concurrently\-committing transactions are sending notify events, exactly which of those will the newly listening session receive? The answer is that the session will receive all events committed after an instant during the transaction\*(Aqs commit step\&. But that is slightly later than any database state that the transaction could have observed in queries\&. This leads to the following rule for using +\fBLISTEN\fR: first execute (and commit!) that command, then in a new transaction inspect the database state as needed by the application logic, then rely on notifications to find out about subsequent changes to the database state\&. The first few received notifications might refer to updates already observed in the initial database inspection, but this is usually harmless\&. +.PP +\fBNOTIFY\fR(7) +contains a more extensive discussion of the use of +\fBLISTEN\fR +and +\fBNOTIFY\fR\&. +.SH "EXAMPLES" +.PP +Configure and execute a listen/notify sequence from +psql: +.sp +.if n \{\ +.RS 4 +.\} +.nf +LISTEN virtual; +NOTIFY virtual; +Asynchronous notification "virtual" received from server process with PID 8448\&. +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBLISTEN\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBNOTIFY\fR(7), \fBUNLISTEN\fR(7) diff --git a/doc/src/sgml/man7/LOAD.7 b/doc/src/sgml/man7/LOAD.7 new file mode 100644 index 0000000..dc4b724 --- /dev/null +++ b/doc/src/sgml/man7/LOAD.7 @@ -0,0 +1,69 @@ +'\" t +.\" Title: LOAD +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "LOAD" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +LOAD \- load a shared library file +.SH "SYNOPSIS" +.sp +.nf +LOAD \*(Aq\fIfilename\fR\*(Aq +.fi +.SH "DESCRIPTION" +.PP +This command loads a shared library file into the +PostgreSQL +server\*(Aqs address space\&. If the file has been loaded already, the command does nothing\&. Shared library files that contain C functions are automatically loaded whenever one of their functions is called\&. Therefore, an explicit +\fBLOAD\fR +is usually only needed to load a library that modifies the server\*(Aqs behavior through +\(lqhooks\(rq +rather than providing a set of functions\&. +.PP +The library file name is typically given as just a bare file name, which is sought in the server\*(Aqs library search path (set by +dynamic_library_path)\&. Alternatively it can be given as a full path name\&. In either case the platform\*(Aqs standard shared library file name extension may be omitted\&. See +Section\ \&38.10.1 +for more information on this topic\&. +.PP +Non\-superusers can only apply +\fBLOAD\fR +to library files located in +$libdir/plugins/ +\(em the specified +\fIfilename\fR +must begin with exactly that string\&. (It is the database administrator\*(Aqs responsibility to ensure that only +\(lqsafe\(rq +libraries are installed there\&.) +.SH "COMPATIBILITY" +.PP +\fBLOAD\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +.PP +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)) diff --git a/doc/src/sgml/man7/LOCK.7 b/doc/src/sgml/man7/LOCK.7 new file mode 100644 index 0000000..c827a3f --- /dev/null +++ b/doc/src/sgml/man7/LOCK.7 @@ -0,0 +1,259 @@ +'\" t +.\" Title: LOCK +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "LOCK" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +LOCK \- lock a table +.SH "SYNOPSIS" +.sp +.nf +LOCK [ TABLE ] [ ONLY ] \fIname\fR [ * ] [, \&.\&.\&.] [ IN \fIlockmode\fR MODE ] [ NOWAIT ] + +where \fIlockmode\fR is one of: + + ACCESS SHARE | ROW SHARE | ROW EXCLUSIVE | SHARE UPDATE EXCLUSIVE + | SHARE | SHARE ROW EXCLUSIVE | EXCLUSIVE | ACCESS EXCLUSIVE +.fi +.SH "DESCRIPTION" +.PP +\fBLOCK TABLE\fR +obtains a table\-level lock, waiting if necessary for any conflicting locks to be released\&. If +NOWAIT +is specified, +\fBLOCK TABLE\fR +does not wait to acquire the desired lock: if it cannot be acquired immediately, the command is aborted and an error is emitted\&. Once obtained, the lock is held for the remainder of the current transaction\&. (There is no +\fBUNLOCK TABLE\fR +command; locks are always released at transaction end\&.) +.PP +When a view is locked, all relations appearing in the view definition query are also locked recursively with the same lock mode\&. +.PP +When acquiring locks automatically for commands that reference tables, +PostgreSQL +always uses the least restrictive lock mode possible\&. +\fBLOCK TABLE\fR +provides for cases when you might need more restrictive locking\&. For example, suppose an application runs a transaction at the +READ COMMITTED +isolation level and needs to ensure that data in a table remains stable for the duration of the transaction\&. To achieve this you could obtain +SHARE +lock mode over the table before querying\&. This will prevent concurrent data changes and ensure subsequent reads of the table see a stable view of committed data, because +SHARE +lock mode conflicts with the +ROW EXCLUSIVE +lock acquired by writers, and your +\fBLOCK TABLE \fR\fB\fIname\fR\fR\fB IN SHARE MODE\fR +statement will wait until any concurrent holders of +ROW EXCLUSIVE +mode locks commit or roll back\&. Thus, once you obtain the lock, there are no uncommitted writes outstanding; furthermore none can begin until you release the lock\&. +.PP +To achieve a similar effect when running a transaction at the +REPEATABLE READ +or +SERIALIZABLE +isolation level, you have to execute the +\fBLOCK TABLE\fR +statement before executing any +\fBSELECT\fR +or data modification statement\&. A +REPEATABLE READ +or +SERIALIZABLE +transaction\*(Aqs view of data will be frozen when its first +\fBSELECT\fR +or data modification statement begins\&. A +\fBLOCK TABLE\fR +later in the transaction will still prevent concurrent writes \(em but it won\*(Aqt ensure that what the transaction reads corresponds to the latest committed values\&. +.PP +If a transaction of this sort is going to change the data in the table, then it should use +SHARE ROW EXCLUSIVE +lock mode instead of +SHARE +mode\&. This ensures that only one transaction of this type runs at a time\&. Without this, a deadlock is possible: two transactions might both acquire +SHARE +mode, and then be unable to also acquire +ROW EXCLUSIVE +mode to actually perform their updates\&. (Note that a transaction\*(Aqs own locks never conflict, so a transaction can acquire +ROW EXCLUSIVE +mode when it holds +SHARE +mode \(em but not if anyone else holds +SHARE +mode\&.) To avoid deadlocks, make sure all transactions acquire locks on the same objects in the same order, and if multiple lock modes are involved for a single object, then transactions should always acquire the most restrictive mode first\&. +.PP +More information about the lock modes and locking strategies can be found in +Section\ \&13.3\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of an existing table to lock\&. If +ONLY +is specified before the table name, only that table is locked\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are locked\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.sp +The command +LOCK TABLE a, b; +is equivalent to +LOCK TABLE a; LOCK TABLE b;\&. The tables are locked one\-by\-one in the order specified in the +\fBLOCK TABLE\fR +command\&. +.RE +.PP +\fIlockmode\fR +.RS 4 +The lock mode specifies which locks this lock conflicts with\&. Lock modes are described in +Section\ \&13.3\&. +.sp +If no lock mode is specified, then +ACCESS EXCLUSIVE, the most restrictive mode, is used\&. +.RE +.PP +NOWAIT +.RS 4 +Specifies that +\fBLOCK TABLE\fR +should not wait for any conflicting locks to be released: if the specified lock(s) cannot be acquired immediately without waiting, the transaction is aborted\&. +.RE +.SH "NOTES" +.PP +LOCK TABLE \&.\&.\&. IN ACCESS SHARE MODE +requires +SELECT +privileges on the target table\&. +LOCK TABLE \&.\&.\&. IN ROW EXCLUSIVE MODE +requires +INSERT, +UPDATE, +DELETE, or +TRUNCATE +privileges on the target table\&. All other forms of +\fBLOCK\fR +require table\-level +UPDATE, +DELETE, or +TRUNCATE +privileges\&. +.PP +The user performing the lock on the view must have the corresponding privilege on the view\&. In addition, by default, the view\*(Aqs owner must have the relevant privileges on the underlying base relations, whereas the user performing the lock does not need any permissions on the underlying base relations\&. However, if the view has +security_invoker +set to +true +(see +\fBCREATE VIEW\fR), the user performing the lock, rather than the view owner, must have the relevant privileges on the underlying base relations\&. +.PP +\fBLOCK TABLE\fR +is useless outside a transaction block: the lock would remain held only to the completion of the statement\&. Therefore +PostgreSQL +reports an error if +\fBLOCK\fR +is used outside a transaction block\&. Use +\fBBEGIN\fR +and +\fBCOMMIT\fR +(or +\fBROLLBACK\fR) to define a transaction block\&. +.PP +\fBLOCK TABLE\fR +only deals with table\-level locks, and so the mode names involving +ROW +are all misnomers\&. These mode names should generally be read as indicating the intention of the user to acquire row\-level locks within the locked table\&. Also, +ROW EXCLUSIVE +mode is a shareable table lock\&. Keep in mind that all the lock modes have identical semantics so far as +\fBLOCK TABLE\fR +is concerned, differing only in the rules about which modes conflict with which\&. For information on how to acquire an actual row\-level lock, see +Section\ \&13.3.2 +and +The Locking Clause +in the +\fBSELECT\fR(7) +documentation\&. +.SH "EXAMPLES" +.PP +Obtain a +SHARE +lock on a primary key table when going to perform inserts into a foreign key table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN WORK; +LOCK TABLE films IN SHARE MODE; +SELECT id FROM films + WHERE name = \*(AqStar Wars: Episode I \- The Phantom Menace\*(Aq; +\-\- Do ROLLBACK if record was not returned +INSERT INTO films_user_comments VALUES + (_id_, \*(AqGREAT! I was waiting for it for so long!\*(Aq); +COMMIT WORK; +.fi +.if n \{\ +.RE +.\} +.PP +Take a +SHARE ROW EXCLUSIVE +lock on a primary key table when going to perform a delete operation: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN WORK; +LOCK TABLE films IN SHARE ROW EXCLUSIVE MODE; +DELETE FROM films_user_comments WHERE id IN + (SELECT id FROM films WHERE rating < 5); +DELETE FROM films WHERE rating < 5; +COMMIT WORK; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBLOCK TABLE\fR +in the SQL standard, which instead uses +\fBSET TRANSACTION\fR +to specify concurrency levels on transactions\&. +PostgreSQL +supports that too; see +SET TRANSACTION (\fBSET_TRANSACTION\fR(7)) +for details\&. +.PP +Except for +ACCESS SHARE, +ACCESS EXCLUSIVE, and +SHARE UPDATE EXCLUSIVE +lock modes, the +PostgreSQL +lock modes and the +\fBLOCK TABLE\fR +syntax are compatible with those present in +Oracle\&. diff --git a/doc/src/sgml/man7/MERGE.7 b/doc/src/sgml/man7/MERGE.7 new file mode 100644 index 0000000..f6abd55 --- /dev/null +++ b/doc/src/sgml/man7/MERGE.7 @@ -0,0 +1,674 @@ +'\" t +.\" Title: MERGE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "MERGE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +MERGE \- conditionally insert, update, or delete rows of a table +.SH "SYNOPSIS" +.sp +.nf +[ WITH \fIwith_query\fR [, \&.\&.\&.] ] +MERGE INTO [ ONLY ] \fItarget_table_name\fR [ * ] [ [ AS ] \fItarget_alias\fR ] +USING \fIdata_source\fR ON \fIjoin_condition\fR +\fIwhen_clause\fR [\&.\&.\&.] + +where \fIdata_source\fR is: + +{ [ ONLY ] \fIsource_table_name\fR [ * ] | ( \fIsource_query\fR ) } [ [ AS ] \fIsource_alias\fR ] + +and \fIwhen_clause\fR is: + +{ WHEN MATCHED [ AND \fIcondition\fR ] THEN { \fImerge_update\fR | \fImerge_delete\fR | DO NOTHING } | + WHEN NOT MATCHED [ AND \fIcondition\fR ] THEN { \fImerge_insert\fR | DO NOTHING } } + +and \fImerge_insert\fR is: + +INSERT [( \fIcolumn_name\fR [, \&.\&.\&.] )] +[ OVERRIDING { SYSTEM | USER } VALUE ] +{ VALUES ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) | DEFAULT VALUES } + +and \fImerge_update\fR is: + +UPDATE SET { \fIcolumn_name\fR = { \fIexpression\fR | DEFAULT } | + ( \fIcolumn_name\fR [, \&.\&.\&.] ) = ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) } [, \&.\&.\&.] + +and \fImerge_delete\fR is: + +DELETE +.fi +.SH "DESCRIPTION" +.PP +\fBMERGE\fR +performs actions that modify rows in the +\fItarget_table_name\fR, using the +\fIdata_source\fR\&. +\fBMERGE\fR +provides a single +SQL +statement that can conditionally +\fBINSERT\fR, +\fBUPDATE\fR +or +\fBDELETE\fR +rows, a task that would otherwise require multiple procedural language statements\&. +.PP +First, the +\fBMERGE\fR +command performs a join from +\fIdata_source\fR +to +\fItarget_table_name\fR +producing zero or more candidate change rows\&. For each candidate change row, the status of +MATCHED +or +NOT MATCHED +is set just once, after which +WHEN +clauses are evaluated in the order specified\&. For each candidate change row, the first clause to evaluate as true is executed\&. No more than one +WHEN +clause is executed for any candidate change row\&. +.PP +\fBMERGE\fR +actions have the same effect as regular +\fBUPDATE\fR, +\fBINSERT\fR, or +\fBDELETE\fR +commands of the same names\&. The syntax of those commands is different, notably that there is no +WHERE +clause and no table name is specified\&. All actions refer to the +\fItarget_table_name\fR, though modifications to other tables may be made using triggers\&. +.PP +When +DO NOTHING +is specified, the source row is skipped\&. Since actions are evaluated in their specified order, +DO NOTHING +can be handy to skip non\-interesting source rows before more fine\-grained handling\&. +.PP +There is no separate +MERGE +privilege\&. If you specify an update action, you must have the +UPDATE +privilege on the column(s) of the +\fItarget_table_name\fR +that are referred to in the +SET +clause\&. If you specify an insert action, you must have the +INSERT +privilege on the +\fItarget_table_name\fR\&. If you specify an delete action, you must have the +DELETE +privilege on the +\fItarget_table_name\fR\&. Privileges are tested once at statement start and are checked whether or not particular +WHEN +clauses are executed\&. You will require the +SELECT +privilege on the +\fIdata_source\fR +and any column(s) of the +\fItarget_table_name\fR +referred to in a +condition\&. +.PP +\fBMERGE\fR +is not supported if the +\fItarget_table_name\fR +is a materialized view, foreign table, or if it has any rules defined on it\&. +.SH "PARAMETERS" +.PP +\fItarget_table_name\fR +.RS 4 +The name (optionally schema\-qualified) of the target table to merge into\&. If +ONLY +is specified before the table name, matching rows are updated or deleted in the named table only\&. If +ONLY +is not specified, matching rows are also updated or deleted in any tables inheriting from the named table\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. The +ONLY +keyword and +* +option do not affect insert actions, which always insert into the named table only\&. +.RE +.PP +\fItarget_alias\fR +.RS 4 +A substitute name for the target table\&. When an alias is provided, it completely hides the actual name of the table\&. For example, given +MERGE INTO foo AS f, the remainder of the +\fBMERGE\fR +statement must refer to this table as +f +not +foo\&. +.RE +.PP +\fIsource_table_name\fR +.RS 4 +The name (optionally schema\-qualified) of the source table, view, or transition table\&. If +ONLY +is specified before the table name, matching rows are included from the named table only\&. If +ONLY +is not specified, matching rows are also included from any tables inheriting from the named table\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +\fIsource_query\fR +.RS 4 +A query (\fBSELECT\fR +statement or +\fBVALUES\fR +statement) that supplies the rows to be merged into the +\fItarget_table_name\fR\&. Refer to the +\fBSELECT\fR(7) +statement or +\fBVALUES\fR(7) +statement for a description of the syntax\&. +.RE +.PP +\fIsource_alias\fR +.RS 4 +A substitute name for the data source\&. When an alias is provided, it completely hides the actual name of the table or the fact that a query was issued\&. +.RE +.PP +\fIjoin_condition\fR +.RS 4 +\fIjoin_condition\fR +is an expression resulting in a value of type +boolean +(similar to a +WHERE +clause) that specifies which rows in the +\fIdata_source\fR +match rows in the +\fItarget_table_name\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBWarning\fR +.ps -1 +.br +Only columns from +\fItarget_table_name\fR +that attempt to match +\fIdata_source\fR +rows should appear in +\fIjoin_condition\fR\&. +\fIjoin_condition\fR +subexpressions that only reference +\fItarget_table_name\fR +columns can affect which action is taken, often in surprising ways\&. +.sp .5v +.RE +.RE +.PP +\fIwhen_clause\fR +.RS 4 +At least one +WHEN +clause is required\&. +.sp +If the +WHEN +clause specifies +WHEN MATCHED +and the candidate change row matches a row in the +\fItarget_table_name\fR, the +WHEN +clause is executed if the +\fIcondition\fR +is absent or it evaluates to +true\&. +.sp +Conversely, if the +WHEN +clause specifies +WHEN NOT MATCHED +and the candidate change row does not match a row in the +\fItarget_table_name\fR, the +WHEN +clause is executed if the +\fIcondition\fR +is absent or it evaluates to +true\&. +.RE +.PP +\fIcondition\fR +.RS 4 +An expression that returns a value of type +boolean\&. If this expression for a +WHEN +clause returns +true, then the action for that clause is executed for that row\&. +.sp +A condition on a +WHEN MATCHED +clause can refer to columns in both the source and the target relations\&. A condition on a +WHEN NOT MATCHED +clause can only refer to columns from the source relation, since by definition there is no matching target row\&. Only the system attributes from the target table are accessible\&. +.RE +.PP +\fImerge_insert\fR +.RS 4 +The specification of an +INSERT +action that inserts one row into the target table\&. The target column names can be listed in any order\&. If no list of column names is given at all, the default is all the columns of the table in their declared order\&. +.sp +Each column not present in the explicit or implicit column list will be filled with a default value, either its declared default value or null if there is none\&. +.sp +If +\fItarget_table_name\fR +is a partitioned table, each row is routed to the appropriate partition and inserted into it\&. If +\fItarget_table_name\fR +is a partition, an error will occur if any input row violates the partition constraint\&. +.sp +Column names may not be specified more than once\&. +\fBINSERT\fR +actions cannot contain sub\-selects\&. +.sp +Only one +VALUES +clause can be specified\&. The +VALUES +clause can only refer to columns from the source relation, since by definition there is no matching target row\&. +.RE +.PP +\fImerge_update\fR +.RS 4 +The specification of an +UPDATE +action that updates the current row of the +\fItarget_table_name\fR\&. Column names may not be specified more than once\&. +.sp +Neither a table name nor a +WHERE +clause are allowed\&. +.RE +.PP +\fImerge_delete\fR +.RS 4 +Specifies a +DELETE +action that deletes the current row of the +\fItarget_table_name\fR\&. Do not include the table name or any other clauses, as you would normally do with a +\fBDELETE\fR(7) +command\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column in the +\fItarget_table_name\fR\&. The column name can be qualified with a subfield name or array subscript, if needed\&. (Inserting into only some fields of a composite column leaves the other fields null\&.) Do not include the table\*(Aqs name in the specification of a target column\&. +.RE +.PP +OVERRIDING SYSTEM VALUE +.RS 4 +Without this clause, it is an error to specify an explicit value (other than +DEFAULT) for an identity column defined as +GENERATED ALWAYS\&. This clause overrides that restriction\&. +.RE +.PP +OVERRIDING USER VALUE +.RS 4 +If this clause is specified, then any values supplied for identity columns defined as +GENERATED BY DEFAULT +are ignored and the default sequence\-generated values are applied\&. +.RE +.PP +DEFAULT VALUES +.RS 4 +All columns will be filled with their default values\&. (An +OVERRIDING +clause is not permitted in this form\&.) +.RE +.PP +\fIexpression\fR +.RS 4 +An expression to assign to the column\&. If used in a +WHEN MATCHED +clause, the expression can use values from the original row in the target table, and values from the +data_source +row\&. If used in a +WHEN NOT MATCHED +clause, the expression can use values from the +data_source\&. +.RE +.PP +DEFAULT +.RS 4 +Set the column to its default value (which will be +NULL +if no specific default expression has been assigned to it)\&. +.RE +.PP +\fIwith_query\fR +.RS 4 +The +WITH +clause allows you to specify one or more subqueries that can be referenced by name in the +\fBMERGE\fR +query\&. See +Section\ \&7.8 +and +\fBSELECT\fR(7) +for details\&. +.RE +.SH "OUTPUTS" +.PP +On successful completion, a +\fBMERGE\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +MERGE \fItotal_count\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fItotal_count\fR +is the total number of rows changed (whether inserted, updated, or deleted)\&. If +\fItotal_count\fR +is 0, no rows were changed in any way\&. +.SH "NOTES" +.PP +The following steps take place during the execution of +\fBMERGE\fR\&. +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Perform any +BEFORE STATEMENT +triggers for all actions specified, whether or not their +WHEN +clauses match\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Perform a join from source to target table\&. The resulting query will be optimized normally and will produce a set of candidate change rows\&. For each candidate change row, +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Evaluate whether each row is +MATCHED +or +NOT MATCHED\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Test each +WHEN +condition in the order specified until one returns true\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +When a condition returns true, perform the following actions: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +Perform any +BEFORE ROW +triggers that fire for the action\*(Aqs event type\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +Perform the specified action, invoking any check constraints on the target table\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Perform any +AFTER ROW +triggers that fire for the action\*(Aqs event type\&. +.RE +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Perform any +AFTER STATEMENT +triggers for actions specified, whether or not they actually occur\&. This is similar to the behavior of an +\fBUPDATE\fR +statement that modifies no rows\&. +.RE +.sp +In summary, statement triggers for an event type (say, +\fBINSERT\fR) will be fired whenever we +\fIspecify\fR +an action of that kind\&. In contrast, row\-level triggers will fire only for the specific event type being +\fIexecuted\fR\&. So a +\fBMERGE\fR +command might fire statement triggers for both +\fBUPDATE\fR +and +\fBINSERT\fR, even though only +\fBUPDATE\fR +row triggers were fired\&. +.PP +You should ensure that the join produces at most one candidate change row for each target row\&. In other words, a target row shouldn\*(Aqt join to more than one data source row\&. If it does, then only one of the candidate change rows will be used to modify the target row; later attempts to modify the row will cause an error\&. This can also occur if row triggers make changes to the target table and the rows so modified are then subsequently also modified by +\fBMERGE\fR\&. If the repeated action is an +\fBINSERT\fR, this will cause a uniqueness violation, while a repeated +\fBUPDATE\fR +or +\fBDELETE\fR +will cause a cardinality violation; the latter behavior is required by the +SQL +standard\&. This differs from historical +PostgreSQL +behavior of joins in +\fBUPDATE\fR +and +\fBDELETE\fR +statements where second and subsequent attempts to modify the same row are simply ignored\&. +.PP +If a +WHEN +clause omits an +AND +sub\-clause, it becomes the final reachable clause of that kind (MATCHED +or +NOT MATCHED)\&. If a later +WHEN +clause of that kind is specified it would be provably unreachable and an error is raised\&. If no final reachable clause is specified of either kind, it is possible that no action will be taken for a candidate change row\&. +.PP +The order in which rows are generated from the data source is indeterminate by default\&. A +\fIsource_query\fR +can be used to specify a consistent ordering, if required, which might be needed to avoid deadlocks between concurrent transactions\&. +.PP +There is no +RETURNING +clause with +\fBMERGE\fR\&. Actions of +\fBINSERT\fR, +\fBUPDATE\fR +and +\fBDELETE\fR +cannot contain +RETURNING +or +WITH +clauses\&. +.PP +When +\fBMERGE\fR +is run concurrently with other commands that modify the target table, the usual transaction isolation rules apply; see +Section\ \&13.2 +for an explanation on the behavior at each isolation level\&. You may also wish to consider using +\fBINSERT \&.\&.\&. ON CONFLICT\fR +as an alternative statement which offers the ability to run an +\fBUPDATE\fR +if a concurrent +\fBINSERT\fR +occurs\&. There are a variety of differences and restrictions between the two statement types and they are not interchangeable\&. +.SH "EXAMPLES" +.PP +Perform maintenance on +customer_accounts +based upon new +recent_transactions\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +MERGE INTO customer_account ca +USING recent_transactions t +ON t\&.customer_id = ca\&.customer_id +WHEN MATCHED THEN + UPDATE SET balance = balance + transaction_value +WHEN NOT MATCHED THEN + INSERT (customer_id, balance) + VALUES (t\&.customer_id, t\&.transaction_value); +.fi +.if n \{\ +.RE +.\} +.PP +Notice that this would be exactly equivalent to the following statement because the +MATCHED +result does not change during execution\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +MERGE INTO customer_account ca +USING (SELECT customer_id, transaction_value FROM recent_transactions) AS t +ON t\&.customer_id = ca\&.customer_id +WHEN MATCHED THEN + UPDATE SET balance = balance + transaction_value +WHEN NOT MATCHED THEN + INSERT (customer_id, balance) + VALUES (t\&.customer_id, t\&.transaction_value); +.fi +.if n \{\ +.RE +.\} +.PP +Attempt to insert a new stock item along with the quantity of stock\&. If the item already exists, instead update the stock count of the existing item\&. Don\*(Aqt allow entries that have zero stock\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +MERGE INTO wines w +USING wine_stock_changes s +ON s\&.winename = w\&.winename +WHEN NOT MATCHED AND s\&.stock_delta > 0 THEN + INSERT VALUES(s\&.winename, s\&.stock_delta) +WHEN MATCHED AND w\&.stock + s\&.stock_delta > 0 THEN + UPDATE SET stock = w\&.stock + s\&.stock_delta +WHEN MATCHED THEN + DELETE; +.fi +.if n \{\ +.RE +.\} +.sp +The +wine_stock_changes +table might be, for example, a temporary table recently loaded into the database\&. +.SH "COMPATIBILITY" +.PP +This command conforms to the +SQL +standard\&. +.PP +The WITH clause and +DO NOTHING +action are extensions to the +SQL +standard\&. diff --git a/doc/src/sgml/man7/MOVE.7 b/doc/src/sgml/man7/MOVE.7 new file mode 100644 index 0000000..3387f0c --- /dev/null +++ b/doc/src/sgml/man7/MOVE.7 @@ -0,0 +1,124 @@ +'\" t +.\" Title: MOVE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "MOVE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +MOVE \- position a cursor +.SH "SYNOPSIS" +.sp +.nf +MOVE [ \fIdirection\fR ] [ FROM | IN ] \fIcursor_name\fR + +where \fIdirection\fR can be one of: + + NEXT + PRIOR + FIRST + LAST + ABSOLUTE \fIcount\fR + RELATIVE \fIcount\fR + \fIcount\fR + ALL + FORWARD + FORWARD \fIcount\fR + FORWARD ALL + BACKWARD + BACKWARD \fIcount\fR + BACKWARD ALL +.fi +.SH "DESCRIPTION" +.PP +\fBMOVE\fR +repositions a cursor without retrieving any data\&. +\fBMOVE\fR +works exactly like the +\fBFETCH\fR +command, except it only positions the cursor and does not return rows\&. +.PP +The parameters for the +\fBMOVE\fR +command are identical to those of the +\fBFETCH\fR +command; refer to +\fBFETCH\fR(7) +for details on syntax and usage\&. +.SH "OUTPUTS" +.PP +On successful completion, a +\fBMOVE\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +MOVE \fIcount\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fIcount\fR +is the number of rows that a +\fBFETCH\fR +command with the same parameters would have returned (possibly zero)\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN WORK; +DECLARE liahona CURSOR FOR SELECT * FROM films; + +\-\- Skip the first 5 rows: +MOVE FORWARD 5 IN liahona; +MOVE 5 + +\-\- Fetch the 6th row from the cursor liahona: +FETCH 1 FROM liahona; + code | title | did | date_prod | kind | len +\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- + P_303 | 48 Hrs | 103 | 1982\-10\-22 | Action | 01:37 +(1 row) + +\-\- Close the cursor liahona and end the transaction: +CLOSE liahona; +COMMIT WORK; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBMOVE\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBCLOSE\fR(7), \fBDECLARE\fR(7), \fBFETCH\fR(7) diff --git a/doc/src/sgml/man7/NOTIFY.7 b/doc/src/sgml/man7/NOTIFY.7 new file mode 100644 index 0000000..c99fe41 --- /dev/null +++ b/doc/src/sgml/man7/NOTIFY.7 @@ -0,0 +1,154 @@ +'\" t +.\" Title: NOTIFY +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "NOTIFY" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +NOTIFY \- generate a notification +.SH "SYNOPSIS" +.sp +.nf +NOTIFY \fIchannel\fR [ , \fIpayload\fR ] +.fi +.SH "DESCRIPTION" +.PP +The +\fBNOTIFY\fR +command sends a notification event together with an optional +\(lqpayload\(rq +string to each client application that has previously executed +\fBLISTEN \fR\fB\fIchannel\fR\fR +for the specified channel name in the current database\&. Notifications are visible to all users\&. +.PP +\fBNOTIFY\fR +provides a simple interprocess communication mechanism for a collection of processes accessing the same +PostgreSQL +database\&. A payload string can be sent along with the notification, and higher\-level mechanisms for passing structured data can be built by using tables in the database to pass additional data from notifier to listener(s)\&. +.PP +The information passed to the client for a notification event includes the notification channel name, the notifying session\*(Aqs server process +PID, and the payload string, which is an empty string if it has not been specified\&. +.PP +It is up to the database designer to define the channel names that will be used in a given database and what each one means\&. Commonly, the channel name is the same as the name of some table in the database, and the notify event essentially means, +\(lqI changed this table, take a look at it to see what\*(Aqs new\(rq\&. But no such association is enforced by the +\fBNOTIFY\fR +and +\fBLISTEN\fR +commands\&. For example, a database designer could use several different channel names to signal different sorts of changes to a single table\&. Alternatively, the payload string could be used to differentiate various cases\&. +.PP +When +\fBNOTIFY\fR +is used to signal the occurrence of changes to a particular table, a useful programming technique is to put the +\fBNOTIFY\fR +in a statement trigger that is triggered by table updates\&. In this way, notification happens automatically when the table is changed, and the application programmer cannot accidentally forget to do it\&. +.PP +\fBNOTIFY\fR +interacts with SQL transactions in some important ways\&. Firstly, if a +\fBNOTIFY\fR +is executed inside a transaction, the notify events are not delivered until and unless the transaction is committed\&. This is appropriate, since if the transaction is aborted, all the commands within it have had no effect, including +\fBNOTIFY\fR\&. But it can be disconcerting if one is expecting the notification events to be delivered immediately\&. Secondly, if a listening session receives a notification signal while it is within a transaction, the notification event will not be delivered to its connected client until just after the transaction is completed (either committed or aborted)\&. Again, the reasoning is that if a notification were delivered within a transaction that was later aborted, one would want the notification to be undone somehow \(em but the server cannot +\(lqtake back\(rq +a notification once it has sent it to the client\&. So notification events are only delivered between transactions\&. The upshot of this is that applications using +\fBNOTIFY\fR +for real\-time signaling should try to keep their transactions short\&. +.PP +If the same channel name is signaled multiple times with identical payload strings within the same transaction, only one instance of the notification event is delivered to listeners\&. On the other hand, notifications with distinct payload strings will always be delivered as distinct notifications\&. Similarly, notifications from different transactions will never get folded into one notification\&. Except for dropping later instances of duplicate notifications, +\fBNOTIFY\fR +guarantees that notifications from the same transaction get delivered in the order they were sent\&. It is also guaranteed that messages from different transactions are delivered in the order in which the transactions committed\&. +.PP +It is common for a client that executes +\fBNOTIFY\fR +to be listening on the same notification channel itself\&. In that case it will get back a notification event, just like all the other listening sessions\&. Depending on the application logic, this could result in useless work, for example, reading a database table to find the same updates that that session just wrote out\&. It is possible to avoid such extra work by noticing whether the notifying session\*(Aqs server process +PID +(supplied in the notification event message) is the same as one\*(Aqs own session\*(Aqs +PID +(available from +libpq)\&. When they are the same, the notification event is one\*(Aqs own work bouncing back, and can be ignored\&. +.SH "PARAMETERS" +.PP +\fIchannel\fR +.RS 4 +Name of the notification channel to be signaled (any identifier)\&. +.RE +.PP +\fIpayload\fR +.RS 4 +The +\(lqpayload\(rq +string to be communicated along with the notification\&. This must be specified as a simple string literal\&. In the default configuration it must be shorter than 8000 bytes\&. (If binary data or large amounts of information need to be communicated, it\*(Aqs best to put it in a database table and send the key of the record\&.) +.RE +.SH "NOTES" +.PP +There is a queue that holds notifications that have been sent but not yet processed by all listening sessions\&. If this queue becomes full, transactions calling +\fBNOTIFY\fR +will fail at commit\&. The queue is quite large (8GB in a standard installation) and should be sufficiently sized for almost every use case\&. However, no cleanup can take place if a session executes +\fBLISTEN\fR +and then enters a transaction for a very long time\&. Once the queue is half full you will see warnings in the log file pointing you to the session that is preventing cleanup\&. In this case you should make sure that this session ends its current transaction so that cleanup can proceed\&. +.PP +The function +\fBpg_notification_queue_usage\fR +returns the fraction of the queue that is currently occupied by pending notifications\&. See +Section\ \&9.26 +for more information\&. +.PP +A transaction that has executed +\fBNOTIFY\fR +cannot be prepared for two\-phase commit\&. +.SS "pg_notify" +.PP +To send a notification you can also use the function +\fBpg_notify\fR(text, text)\&. The function takes the channel name as the first argument and the payload as the second\&. The function is much easier to use than the +\fBNOTIFY\fR +command if you need to work with non\-constant channel names and payloads\&. +.SH "EXAMPLES" +.PP +Configure and execute a listen/notify sequence from +psql: +.sp +.if n \{\ +.RS 4 +.\} +.nf +LISTEN virtual; +NOTIFY virtual; +Asynchronous notification "virtual" received from server process with PID 8448\&. +NOTIFY virtual, \*(AqThis is the payload\*(Aq; +Asynchronous notification "virtual" with payload "This is the payload" received from server process with PID 8448\&. + +LISTEN foo; +SELECT pg_notify(\*(Aqfo\*(Aq || \*(Aqo\*(Aq, \*(Aqpay\*(Aq || \*(Aqload\*(Aq); +Asynchronous notification "foo" with payload "payload" received from server process with PID 14728\&. +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBNOTIFY\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBLISTEN\fR(7), \fBUNLISTEN\fR(7) diff --git a/doc/src/sgml/man7/PREPARE.7 b/doc/src/sgml/man7/PREPARE.7 new file mode 100644 index 0000000..66e4675 --- /dev/null +++ b/doc/src/sgml/man7/PREPARE.7 @@ -0,0 +1,189 @@ +'\" t +.\" Title: PREPARE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "PREPARE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +PREPARE \- prepare a statement for execution +.SH "SYNOPSIS" +.sp +.nf +PREPARE \fIname\fR [ ( \fIdata_type\fR [, \&.\&.\&.] ) ] AS \fIstatement\fR +.fi +.SH "DESCRIPTION" +.PP +\fBPREPARE\fR +creates a prepared statement\&. A prepared statement is a server\-side object that can be used to optimize performance\&. When the +\fBPREPARE\fR +statement is executed, the specified statement is parsed, analyzed, and rewritten\&. When an +\fBEXECUTE\fR +command is subsequently issued, the prepared statement is planned and executed\&. This division of labor avoids repetitive parse analysis work, while allowing the execution plan to depend on the specific parameter values supplied\&. +.PP +Prepared statements can take parameters: values that are substituted into the statement when it is executed\&. When creating the prepared statement, refer to parameters by position, using +$1, +$2, etc\&. A corresponding list of parameter data types can optionally be specified\&. When a parameter\*(Aqs data type is not specified or is declared as +unknown, the type is inferred from the context in which the parameter is first referenced (if possible)\&. When executing the statement, specify the actual values for these parameters in the +\fBEXECUTE\fR +statement\&. Refer to +\fBEXECUTE\fR(7) +for more information about that\&. +.PP +Prepared statements only last for the duration of the current database session\&. When the session ends, the prepared statement is forgotten, so it must be recreated before being used again\&. This also means that a single prepared statement cannot be used by multiple simultaneous database clients; however, each client can create their own prepared statement to use\&. Prepared statements can be manually cleaned up using the +\fBDEALLOCATE\fR +command\&. +.PP +Prepared statements potentially have the largest performance advantage when a single session is being used to execute a large number of similar statements\&. The performance difference will be particularly significant if the statements are complex to plan or rewrite, e\&.g\&., if the query involves a join of many tables or requires the application of several rules\&. If the statement is relatively simple to plan and rewrite but relatively expensive to execute, the performance advantage of prepared statements will be less noticeable\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +An arbitrary name given to this particular prepared statement\&. It must be unique within a single session and is subsequently used to execute or deallocate a previously prepared statement\&. +.RE +.PP +\fIdata_type\fR +.RS 4 +The data type of a parameter to the prepared statement\&. If the data type of a particular parameter is unspecified or is specified as +unknown, it will be inferred from the context in which the parameter is first referenced\&. To refer to the parameters in the prepared statement itself, use +$1, +$2, etc\&. +.RE +.PP +\fIstatement\fR +.RS 4 +Any +\fBSELECT\fR, +\fBINSERT\fR, +\fBUPDATE\fR, +\fBDELETE\fR, +\fBMERGE\fR, or +\fBVALUES\fR +statement\&. +.RE +.SH "NOTES" +.PP +A prepared statement can be executed with either a +generic plan +or a +custom plan\&. A generic plan is the same across all executions, while a custom plan is generated for a specific execution using the parameter values given in that call\&. Use of a generic plan avoids planning overhead, but in some situations a custom plan will be much more efficient to execute because the planner can make use of knowledge of the parameter values\&. (Of course, if the prepared statement has no parameters, then this is moot and a generic plan is always used\&.) +.PP +By default (that is, when +plan_cache_mode +is set to +auto), the server will automatically choose whether to use a generic or custom plan for a prepared statement that has parameters\&. The current rule for this is that the first five executions are done with custom plans and the average estimated cost of those plans is calculated\&. Then a generic plan is created and its estimated cost is compared to the average custom\-plan cost\&. Subsequent executions use the generic plan if its cost is not so much higher than the average custom\-plan cost as to make repeated replanning seem preferable\&. +.PP +This heuristic can be overridden, forcing the server to use either generic or custom plans, by setting +\fIplan_cache_mode\fR +to +force_generic_plan +or +force_custom_plan +respectively\&. This setting is primarily useful if the generic plan\*(Aqs cost estimate is badly off for some reason, allowing it to be chosen even though its actual cost is much more than that of a custom plan\&. +.PP +To examine the query plan +PostgreSQL +is using for a prepared statement, use +\fBEXPLAIN\fR, for example +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXPLAIN EXECUTE \fIname\fR(\fIparameter_values\fR); +.fi +.if n \{\ +.RE +.\} +.sp +If a generic plan is in use, it will contain parameter symbols +$\fIn\fR, while a custom plan will have the supplied parameter values substituted into it\&. +.PP +For more information on query planning and the statistics collected by +PostgreSQL +for that purpose, see the +\fBANALYZE\fR(7) +documentation\&. +.PP +Although the main point of a prepared statement is to avoid repeated parse analysis and planning of the statement, +PostgreSQL +will force re\-analysis and re\-planning of the statement before using it whenever database objects used in the statement have undergone definitional (DDL) changes or their planner statistics have been updated since the previous use of the prepared statement\&. Also, if the value of +search_path +changes from one use to the next, the statement will be re\-parsed using the new +\fIsearch_path\fR\&. (This latter behavior is new as of +PostgreSQL +9\&.3\&.) These rules make use of a prepared statement semantically almost equivalent to re\-submitting the same query text over and over, but with a performance benefit if no object definitions are changed, especially if the best plan remains the same across uses\&. An example of a case where the semantic equivalence is not perfect is that if the statement refers to a table by an unqualified name, and then a new table of the same name is created in a schema appearing earlier in the +\fIsearch_path\fR, no automatic re\-parse will occur since no object used in the statement changed\&. However, if some other change forces a re\-parse, the new table will be referenced in subsequent uses\&. +.PP +You can see all prepared statements available in the session by querying the +pg_prepared_statements +system view\&. +.SH "EXAMPLES" +.PP +Create a prepared statement for an +\fBINSERT\fR +statement, and then execute it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PREPARE fooplan (int, text, bool, numeric) AS + INSERT INTO foo VALUES($1, $2, $3, $4); +EXECUTE fooplan(1, \*(AqHunter Valley\*(Aq, \*(Aqt\*(Aq, 200\&.00); +.fi +.if n \{\ +.RE +.\} +.PP +Create a prepared statement for a +\fBSELECT\fR +statement, and then execute it: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PREPARE usrrptplan (int) AS + SELECT * FROM users u, logs l WHERE u\&.usrid=$1 AND u\&.usrid=l\&.usrid + AND l\&.date = $2; +EXECUTE usrrptplan(1, current_date); +.fi +.if n \{\ +.RE +.\} +.sp +In this example, the data type of the second parameter is not specified, so it is inferred from the context in which +$2 +is used\&. +.SH "COMPATIBILITY" +.PP +The SQL standard includes a +\fBPREPARE\fR +statement, but it is only for use in embedded SQL\&. This version of the +\fBPREPARE\fR +statement also uses a somewhat different syntax\&. +.SH "SEE ALSO" +\fBDEALLOCATE\fR(7), \fBEXECUTE\fR(7) diff --git a/doc/src/sgml/man7/PREPARE_TRANSACTION.7 b/doc/src/sgml/man7/PREPARE_TRANSACTION.7 new file mode 100644 index 0000000..14e1f87 --- /dev/null +++ b/doc/src/sgml/man7/PREPARE_TRANSACTION.7 @@ -0,0 +1,147 @@ +'\" t +.\" Title: PREPARE TRANSACTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "PREPARE TRANSACTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +PREPARE_TRANSACTION \- prepare the current transaction for two\-phase commit +.SH "SYNOPSIS" +.sp +.nf +PREPARE TRANSACTION \fItransaction_id\fR +.fi +.SH "DESCRIPTION" +.PP +\fBPREPARE TRANSACTION\fR +prepares the current transaction for two\-phase commit\&. After this command, the transaction is no longer associated with the current session; instead, its state is fully stored on disk, and there is a very high probability that it can be committed successfully, even if a database crash occurs before the commit is requested\&. +.PP +Once prepared, a transaction can later be committed or rolled back with +\fBCOMMIT PREPARED\fR +or +\fBROLLBACK PREPARED\fR, respectively\&. Those commands can be issued from any session, not only the one that executed the original transaction\&. +.PP +From the point of view of the issuing session, +\fBPREPARE TRANSACTION\fR +is not unlike a +\fBROLLBACK\fR +command: after executing it, there is no active current transaction, and the effects of the prepared transaction are no longer visible\&. (The effects will become visible again if the transaction is committed\&.) +.PP +If the +\fBPREPARE TRANSACTION\fR +command fails for any reason, it becomes a +\fBROLLBACK\fR: the current transaction is canceled\&. +.SH "PARAMETERS" +.PP +\fItransaction_id\fR +.RS 4 +An arbitrary identifier that later identifies this transaction for +\fBCOMMIT PREPARED\fR +or +\fBROLLBACK PREPARED\fR\&. The identifier must be written as a string literal, and must be less than 200 bytes long\&. It must not be the same as the identifier used for any currently prepared transaction\&. +.RE +.SH "NOTES" +.PP +\fBPREPARE TRANSACTION\fR +is not intended for use in applications or interactive sessions\&. Its purpose is to allow an external transaction manager to perform atomic global transactions across multiple databases or other transactional resources\&. Unless you\*(Aqre writing a transaction manager, you probably shouldn\*(Aqt be using +\fBPREPARE TRANSACTION\fR\&. +.PP +This command must be used inside a transaction block\&. Use +\fBBEGIN\fR +to start one\&. +.PP +It is not currently allowed to +\fBPREPARE\fR +a transaction that has executed any operations involving temporary tables or the session\*(Aqs temporary namespace, created any cursors +WITH HOLD, or executed +\fBLISTEN\fR, +\fBUNLISTEN\fR, or +\fBNOTIFY\fR\&. Those features are too tightly tied to the current session to be useful in a transaction to be prepared\&. +.PP +If the transaction modified any run\-time parameters with +\fBSET\fR +(without the +LOCAL +option), those effects persist after +\fBPREPARE TRANSACTION\fR, and will not be affected by any later +\fBCOMMIT PREPARED\fR +or +\fBROLLBACK PREPARED\fR\&. Thus, in this one respect +\fBPREPARE TRANSACTION\fR +acts more like +\fBCOMMIT\fR +than +\fBROLLBACK\fR\&. +.PP +All currently available prepared transactions are listed in the +pg_prepared_xacts +system view\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +It is unwise to leave transactions in the prepared state for a long time\&. This will interfere with the ability of +\fBVACUUM\fR +to reclaim storage, and in extreme cases could cause the database to shut down to prevent transaction ID wraparound (see +Section\ \&25.1.5)\&. Keep in mind also that the transaction continues to hold whatever locks it held\&. The intended usage of the feature is that a prepared transaction will normally be committed or rolled back as soon as an external transaction manager has verified that other databases are also prepared to commit\&. +.PP +If you have not set up an external transaction manager to track prepared transactions and ensure they get closed out promptly, it is best to keep the prepared\-transaction feature disabled by setting +max_prepared_transactions +to zero\&. This will prevent accidental creation of prepared transactions that might then be forgotten and eventually cause problems\&. +.sp .5v +.RE +.SH "EXAMPLES" +.PP +Prepare the current transaction for two\-phase commit, using +foobar +as the transaction identifier: +.sp +.if n \{\ +.RS 4 +.\} +.nf +PREPARE TRANSACTION \*(Aqfoobar\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBPREPARE TRANSACTION\fR +is a +PostgreSQL +extension\&. It is intended for use by external transaction management systems, some of which are covered by standards (such as X/Open XA), but the SQL side of those systems is not standardized\&. +.SH "SEE ALSO" +COMMIT PREPARED (\fBCOMMIT_PREPARED\fR(7)), ROLLBACK PREPARED (\fBROLLBACK_PREPARED\fR(7)) diff --git a/doc/src/sgml/man7/REASSIGN_OWNED.7 b/doc/src/sgml/man7/REASSIGN_OWNED.7 new file mode 100644 index 0000000..6ef51cb --- /dev/null +++ b/doc/src/sgml/man7/REASSIGN_OWNED.7 @@ -0,0 +1,91 @@ +'\" t +.\" Title: REASSIGN OWNED +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "REASSIGN OWNED" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +REASSIGN_OWNED \- change the ownership of database objects owned by a database role +.SH "SYNOPSIS" +.sp +.nf +REASSIGN OWNED BY { \fIold_role\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } [, \&.\&.\&.] + TO { \fInew_role\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } +.fi +.SH "DESCRIPTION" +.PP +\fBREASSIGN OWNED\fR +instructs the system to change the ownership of database objects owned by any of the +\fIold_roles\fR +to +\fInew_role\fR\&. +.SH "PARAMETERS" +.PP +\fIold_role\fR +.RS 4 +The name of a role\&. The ownership of all the objects within the current database, and of all shared objects (databases, tablespaces), owned by this role will be reassigned to +\fInew_role\fR\&. +.RE +.PP +\fInew_role\fR +.RS 4 +The name of the role that will be made the new owner of the affected objects\&. +.RE +.SH "NOTES" +.PP +\fBREASSIGN OWNED\fR +is often used to prepare for the removal of one or more roles\&. Because +\fBREASSIGN OWNED\fR +does not affect objects within other databases, it is usually necessary to execute this command in each database that contains objects owned by a role that is to be removed\&. +.PP +\fBREASSIGN OWNED\fR +requires membership on both the source role(s) and the target role\&. +.PP +The +\fBDROP OWNED\fR +command is an alternative that simply drops all the database objects owned by one or more roles\&. +.PP +The +\fBREASSIGN OWNED\fR +command does not affect any privileges granted to the +\fIold_roles\fR +on objects that are not owned by them\&. Likewise, it does not affect default privileges created with +\fBALTER DEFAULT PRIVILEGES\fR\&. Use +\fBDROP OWNED\fR +to revoke such privileges\&. +.PP +See +Section\ \&22.4 +for more discussion\&. +.SH "COMPATIBILITY" +.PP +The +\fBREASSIGN OWNED\fR +command is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +DROP OWNED (\fBDROP_OWNED\fR(7)), DROP ROLE (\fBDROP_ROLE\fR(7)), ALTER DATABASE (\fBALTER_DATABASE\fR(7)) diff --git a/doc/src/sgml/man7/REFRESH_MATERIALIZED_VIEW.7 b/doc/src/sgml/man7/REFRESH_MATERIALIZED_VIEW.7 new file mode 100644 index 0000000..cb0cf0d --- /dev/null +++ b/doc/src/sgml/man7/REFRESH_MATERIALIZED_VIEW.7 @@ -0,0 +1,117 @@ +'\" t +.\" Title: REFRESH MATERIALIZED VIEW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "REFRESH MATERIALIZED VIEW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +REFRESH_MATERIALIZED_VIEW \- replace the contents of a materialized view +.SH "SYNOPSIS" +.sp +.nf +REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] \fIname\fR + [ WITH [ NO ] DATA ] +.fi +.SH "DESCRIPTION" +.PP +\fBREFRESH MATERIALIZED VIEW\fR +completely replaces the contents of a materialized view\&. To execute this command you must be the owner of the materialized view\&. The old contents are discarded\&. If +WITH DATA +is specified (or defaults) the backing query is executed to provide the new data, and the materialized view is left in a scannable state\&. If +WITH NO DATA +is specified no new data is generated and the materialized view is left in an unscannable state\&. +.PP +CONCURRENTLY +and +WITH NO DATA +may not be specified together\&. +.SH "PARAMETERS" +.PP +CONCURRENTLY +.RS 4 +Refresh the materialized view without locking out concurrent selects on the materialized view\&. Without this option a refresh which affects a lot of rows will tend to use fewer resources and complete more quickly, but could block other connections which are trying to read from the materialized view\&. This option may be faster in cases where a small number of rows are affected\&. +.sp +This option is only allowed if there is at least one +UNIQUE +index on the materialized view which uses only column names and includes all rows; that is, it must not be an expression index or include a +WHERE +clause\&. +.sp +This option may not be used when the materialized view is not already populated\&. +.sp +Even with this option only one +REFRESH +at a time may run against any one materialized view\&. +.RE +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of the materialized view to refresh\&. +.RE +.SH "NOTES" +.PP +If there is an +ORDER BY +clause in the materialized view\*(Aqs defining query, the original contents of the materialized view will be ordered that way; but +\fBREFRESH MATERIALIZED VIEW\fR +does not guarantee to preserve that ordering\&. +.SH "EXAMPLES" +.PP +This command will replace the contents of the materialized view called +order_summary +using the query from the materialized view\*(Aqs definition, and leave it in a scannable state: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REFRESH MATERIALIZED VIEW order_summary; +.fi +.if n \{\ +.RE +.\} +.PP +This command will free storage associated with the materialized view +annual_statistics_basis +and leave it in an unscannable state: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REFRESH MATERIALIZED VIEW annual_statistics_basis WITH NO DATA; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBREFRESH MATERIALIZED VIEW\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +CREATE MATERIALIZED VIEW (\fBCREATE_MATERIALIZED_VIEW\fR(7)), ALTER MATERIALIZED VIEW (\fBALTER_MATERIALIZED_VIEW\fR(7)), DROP MATERIALIZED VIEW (\fBDROP_MATERIALIZED_VIEW\fR(7)) diff --git a/doc/src/sgml/man7/REINDEX.7 b/doc/src/sgml/man7/REINDEX.7 new file mode 100644 index 0000000..216f6db --- /dev/null +++ b/doc/src/sgml/man7/REINDEX.7 @@ -0,0 +1,510 @@ +'\" t +.\" Title: REINDEX +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "REINDEX" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +REINDEX \- rebuild indexes +.SH "SYNOPSIS" +.sp +.nf +REINDEX [ ( \fIoption\fR [, \&.\&.\&.] ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } [ CONCURRENTLY ] \fIname\fR + +where \fIoption\fR can be one of: + + CONCURRENTLY [ \fIboolean\fR ] + TABLESPACE \fInew_tablespace\fR + VERBOSE [ \fIboolean\fR ] +.fi +.SH "DESCRIPTION" +.PP +\fBREINDEX\fR +rebuilds an index using the data stored in the index\*(Aqs table, replacing the old copy of the index\&. There are several scenarios in which to use +\fBREINDEX\fR: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An index has become corrupted, and no longer contains valid data\&. Although in theory this should never happen, in practice indexes can become corrupted due to software bugs or hardware failures\&. +\fBREINDEX\fR +provides a recovery method\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +An index has become +\(lqbloated\(rq, that is it contains many empty or nearly\-empty pages\&. This can occur with B\-tree indexes in +PostgreSQL +under certain uncommon access patterns\&. +\fBREINDEX\fR +provides a way to reduce the space consumption of the index by writing a new version of the index without the dead pages\&. See +Section\ \&25.2 +for more information\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +You have altered a storage parameter (such as fillfactor) for an index, and wish to ensure that the change has taken full effect\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +If an index build fails with the +CONCURRENTLY +option, this index is left as +\(lqinvalid\(rq\&. Such indexes are useless but it can be convenient to use +\fBREINDEX\fR +to rebuild them\&. Note that only +\fBREINDEX INDEX\fR +is able to perform a concurrent build on an invalid index\&. +.RE +.SH "PARAMETERS" +.PP +INDEX +.RS 4 +Recreate the specified index\&. This form of +\fBREINDEX\fR +cannot be executed inside a transaction block when used with a partitioned index\&. +.RE +.PP +TABLE +.RS 4 +Recreate all indexes of the specified table\&. If the table has a secondary +\(lqTOAST\(rq +table, that is reindexed as well\&. This form of +\fBREINDEX\fR +cannot be executed inside a transaction block when used with a partitioned table\&. +.RE +.PP +SCHEMA +.RS 4 +Recreate all indexes of the specified schema\&. If a table of this schema has a secondary +\(lqTOAST\(rq +table, that is reindexed as well\&. Indexes on shared system catalogs are also processed\&. This form of +\fBREINDEX\fR +cannot be executed inside a transaction block\&. +.RE +.PP +DATABASE +.RS 4 +Recreate all indexes within the current database\&. Indexes on shared system catalogs are also processed\&. This form of +\fBREINDEX\fR +cannot be executed inside a transaction block\&. +.RE +.PP +SYSTEM +.RS 4 +Recreate all indexes on system catalogs within the current database\&. Indexes on shared system catalogs are included\&. Indexes on user tables are not processed\&. This form of +\fBREINDEX\fR +cannot be executed inside a transaction block\&. +.RE +.PP +\fIname\fR +.RS 4 +The name of the specific index, table, or database to be reindexed\&. Index and table names can be schema\-qualified\&. Presently, +\fBREINDEX DATABASE\fR +and +\fBREINDEX SYSTEM\fR +can only reindex the current database, so their parameter must match the current database\*(Aqs name\&. +.RE +.PP +CONCURRENTLY +.RS 4 +When this option is used, +PostgreSQL +will rebuild the index without taking any locks that prevent concurrent inserts, updates, or deletes on the table; whereas a standard index rebuild locks out writes (but not reads) on the table until it\*(Aqs done\&. There are several caveats to be aware of when using this option \(em see +Rebuilding Indexes Concurrently +below\&. +.sp +For temporary tables, +\fBREINDEX\fR +is always non\-concurrent, as no other session can access them, and non\-concurrent reindex is cheaper\&. +.RE +.PP +TABLESPACE +.RS 4 +Specifies that indexes will be rebuilt on a new tablespace\&. +.RE +.PP +VERBOSE +.RS 4 +Prints a progress report as each index is reindexed\&. +.RE +.PP +\fIboolean\fR +.RS 4 +Specifies whether the selected option should be turned on or off\&. You can write +TRUE, +ON, or +1 +to enable the option, and +FALSE, +OFF, or +0 +to disable it\&. The +\fIboolean\fR +value can also be omitted, in which case +TRUE +is assumed\&. +.RE +.PP +\fInew_tablespace\fR +.RS 4 +The tablespace where indexes will be rebuilt\&. +.RE +.SH "NOTES" +.PP +If you suspect corruption of an index on a user table, you can simply rebuild that index, or all indexes on the table, using +\fBREINDEX INDEX\fR +or +\fBREINDEX TABLE\fR\&. +.PP +Things are more difficult if you need to recover from corruption of an index on a system table\&. In this case it\*(Aqs important for the system to not have used any of the suspect indexes itself\&. (Indeed, in this sort of scenario you might find that server processes are crashing immediately at start\-up, due to reliance on the corrupted indexes\&.) To recover safely, the server must be started with the +\fB\-P\fR +option, which prevents it from using indexes for system catalog lookups\&. +.PP +One way to do this is to shut down the server and start a single\-user +PostgreSQL +server with the +\fB\-P\fR +option included on its command line\&. Then, +\fBREINDEX DATABASE\fR, +\fBREINDEX SYSTEM\fR, +\fBREINDEX TABLE\fR, or +\fBREINDEX INDEX\fR +can be issued, depending on how much you want to reconstruct\&. If in doubt, use +\fBREINDEX SYSTEM\fR +to select reconstruction of all system indexes in the database\&. Then quit the single\-user server session and restart the regular server\&. See the +\fBpostgres\fR(1) +reference page for more information about how to interact with the single\-user server interface\&. +.PP +Alternatively, a regular server session can be started with +\fB\-P\fR +included in its command line options\&. The method for doing this varies across clients, but in all +libpq\-based clients, it is possible to set the +\fBPGOPTIONS\fR +environment variable to +\-P +before starting the client\&. Note that while this method does not require locking out other clients, it might still be wise to prevent other users from connecting to the damaged database until repairs have been completed\&. +.PP +\fBREINDEX\fR +is similar to a drop and recreate of the index in that the index contents are rebuilt from scratch\&. However, the locking considerations are rather different\&. +\fBREINDEX\fR +locks out writes but not reads of the index\*(Aqs parent table\&. It also takes an +ACCESS EXCLUSIVE +lock on the specific index being processed, which will block reads that attempt to use that index\&. In particular, the query planner tries to take an +ACCESS SHARE +lock on every index of the table, regardless of the query, and so +\fBREINDEX\fR +blocks virtually any queries except for some prepared queries whose plan has been cached and which don\*(Aqt use this very index\&. In contrast, +\fBDROP INDEX\fR +momentarily takes an +ACCESS EXCLUSIVE +lock on the parent table, blocking both writes and reads\&. The subsequent +\fBCREATE INDEX\fR +locks out writes but not reads; since the index is not there, no read will attempt to use it, meaning that there will be no blocking but reads might be forced into expensive sequential scans\&. +.PP +Reindexing a single index or table requires being the owner of that index or table\&. Reindexing a schema or database requires being the owner of that schema or database\&. Note specifically that it\*(Aqs thus possible for non\-superusers to rebuild indexes of tables owned by other users\&. However, as a special exception, when +\fBREINDEX DATABASE\fR, +\fBREINDEX SCHEMA\fR +or +\fBREINDEX SYSTEM\fR +is issued by a non\-superuser, indexes on shared catalogs will be skipped unless the user owns the catalog (which typically won\*(Aqt be the case)\&. Of course, superusers can always reindex anything\&. +.PP +Reindexing partitioned indexes or partitioned tables is supported with +\fBREINDEX INDEX\fR +or +\fBREINDEX TABLE\fR, respectively\&. Each partition of the specified partitioned relation is reindexed in a separate transaction\&. Those commands cannot be used inside a transaction block when working on a partitioned table or index\&. +.PP +When using the +TABLESPACE +clause with +\fBREINDEX\fR +on a partitioned index or table, only the tablespace references of the leaf partitions are updated\&. As partitioned indexes are not updated, it is recommended to separately use +\fBALTER TABLE ONLY\fR +on them so as any new partitions attached inherit the new tablespace\&. On failure, it may not have moved all the indexes to the new tablespace\&. Re\-running the command will rebuild all the leaf partitions and move previously\-unprocessed indexes to the new tablespace\&. +.PP +If +SCHEMA, +DATABASE +or +SYSTEM +is used with +TABLESPACE, system relations are skipped and a single +WARNING +will be generated\&. Indexes on TOAST tables are rebuilt, but not moved to the new tablespace\&. +.SS "Rebuilding Indexes Concurrently" +.PP +Rebuilding an index can interfere with regular operation of a database\&. Normally +PostgreSQL +locks the table whose index is rebuilt against writes and performs the entire index build with a single scan of the table\&. Other transactions can still read the table, but if they try to insert, update, or delete rows in the table they will block until the index rebuild is finished\&. This could have a severe effect if the system is a live production database\&. Very large tables can take many hours to be indexed, and even for smaller tables, an index rebuild can lock out writers for periods that are unacceptably long for a production system\&. +.PP +PostgreSQL +supports rebuilding indexes with minimum locking of writes\&. This method is invoked by specifying the +CONCURRENTLY +option of +\fBREINDEX\fR\&. When this option is used, +PostgreSQL +must perform two scans of the table for each index that needs to be rebuilt and wait for termination of all existing transactions that could potentially use the index\&. This method requires more total work than a standard index rebuild and takes significantly longer to complete as it needs to wait for unfinished transactions that might modify the index\&. However, since it allows normal operations to continue while the index is being rebuilt, this method is useful for rebuilding indexes in a production environment\&. Of course, the extra CPU, memory and I/O load imposed by the index rebuild may slow down other operations\&. +.PP +The following steps occur in a concurrent reindex\&. Each step is run in a separate transaction\&. If there are multiple indexes to be rebuilt, then each step loops through all the indexes before moving to the next step\&. +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +A new transient index definition is added to the catalog +pg_index\&. This definition will be used to replace the old index\&. A +SHARE UPDATE EXCLUSIVE +lock at session level is taken on the indexes being reindexed as well as their associated tables to prevent any schema modification while processing\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +A first pass to build the index is done for each new index\&. Once the index is built, its flag +pg_index\&.indisready +is switched to +\(lqtrue\(rq +to make it ready for inserts, making it visible to other sessions once the transaction that performed the build is finished\&. This step is done in a separate transaction for each index\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +Then a second pass is performed to add tuples that were added while the first pass was running\&. This step is also done in a separate transaction for each index\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +All the constraints that refer to the index are changed to refer to the new index definition, and the names of the indexes are changed\&. At this point, +pg_index\&.indisvalid +is switched to +\(lqtrue\(rq +for the new index and to +\(lqfalse\(rq +for the old, and a cache invalidation is done causing all sessions that referenced the old index to be invalidated\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +The old indexes have +pg_index\&.indisready +switched to +\(lqfalse\(rq +to prevent any new tuple insertions, after waiting for running queries that might reference the old index to complete\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +The old indexes are dropped\&. The +SHARE UPDATE EXCLUSIVE +session locks for the indexes and the table are released\&. +.RE +.PP +If a problem arises while rebuilding the indexes, such as a uniqueness violation in a unique index, the +\fBREINDEX\fR +command will fail but leave behind an +\(lqinvalid\(rq +new index in addition to the pre\-existing one\&. This index will be ignored for querying purposes because it might be incomplete; however it will still consume update overhead\&. The +psql +\fB\ed\fR +command will report such an index as +INVALID: +.sp +.if n \{\ +.RS 4 +.\} +.nf +postgres=# \ed tab + Table "public\&.tab" + Column | Type | Modifiers +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\- + col | integer | +Indexes: + "idx" btree (col) + "idx_ccnew" btree (col) INVALID +.fi +.if n \{\ +.RE +.\} +.sp +If the index marked +INVALID +is suffixed +ccnew, then it corresponds to the transient index created during the concurrent operation, and the recommended recovery method is to drop it using +DROP INDEX, then attempt +\fBREINDEX CONCURRENTLY\fR +again\&. If the invalid index is instead suffixed +ccold, it corresponds to the original index which could not be dropped; the recommended recovery method is to just drop said index, since the rebuild proper has been successful\&. +.PP +Regular index builds permit other regular index builds on the same table to occur simultaneously, but only one concurrent index build can occur on a table at a time\&. In both cases, no other types of schema modification on the table are allowed meanwhile\&. Another difference is that a regular +\fBREINDEX TABLE\fR +or +\fBREINDEX INDEX\fR +command can be performed within a transaction block, but +\fBREINDEX CONCURRENTLY\fR +cannot\&. +.PP +Like any long\-running transaction, +\fBREINDEX\fR +on a table can affect which tuples can be removed by concurrent +\fBVACUUM\fR +on any other table\&. +.PP +\fBREINDEX SYSTEM\fR +does not support +\fBCONCURRENTLY\fR +since system catalogs cannot be reindexed concurrently\&. +.PP +Furthermore, indexes for exclusion constraints cannot be reindexed concurrently\&. If such an index is named directly in this command, an error is raised\&. If a table or database with exclusion constraint indexes is reindexed concurrently, those indexes will be skipped\&. (It is possible to reindex such indexes without the +\fBCONCURRENTLY\fR +option\&.) +.PP +Each backend running +\fBREINDEX\fR +will report its progress in the +pg_stat_progress_create_index +view\&. See +Section\ \&28.4.2 +for details\&. +.SH "EXAMPLES" +.PP +Rebuild a single index: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REINDEX INDEX my_index; +.fi +.if n \{\ +.RE +.\} +.PP +Rebuild all the indexes on the table +my_table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REINDEX TABLE my_table; +.fi +.if n \{\ +.RE +.\} +.PP +Rebuild all indexes in a particular database, without trusting the system indexes to be valid already: +.sp +.if n \{\ +.RS 4 +.\} +.nf +$ \fBexport PGOPTIONS="\-P"\fR +$ \fBpsql broken_db\fR +\&.\&.\&. +broken_db=> REINDEX DATABASE broken_db; +broken_db=> \eq +.fi +.if n \{\ +.RE +.\} +.PP +Rebuild indexes for a table, without blocking read and write operations on involved relations while reindexing is in progress: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REINDEX TABLE CONCURRENTLY my_broken_table; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBREINDEX\fR +command in the SQL standard\&. +.SH "SEE ALSO" +CREATE INDEX (\fBCREATE_INDEX\fR(7)), DROP INDEX (\fBDROP_INDEX\fR(7)), \fBreindexdb\fR(1), Section\ \&28.4.2 diff --git a/doc/src/sgml/man7/RELEASE_SAVEPOINT.7 b/doc/src/sgml/man7/RELEASE_SAVEPOINT.7 new file mode 100644 index 0000000..4307fd5 --- /dev/null +++ b/doc/src/sgml/man7/RELEASE_SAVEPOINT.7 @@ -0,0 +1,90 @@ +'\" t +.\" Title: RELEASE SAVEPOINT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "RELEASE SAVEPOINT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +RELEASE_SAVEPOINT \- destroy a previously defined savepoint +.SH "SYNOPSIS" +.sp +.nf +RELEASE [ SAVEPOINT ] \fIsavepoint_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBRELEASE SAVEPOINT\fR +destroys a savepoint previously defined in the current transaction\&. +.PP +Destroying a savepoint makes it unavailable as a rollback point, but it has no other user visible behavior\&. It does not undo the effects of commands executed after the savepoint was established\&. (To do that, see +ROLLBACK TO SAVEPOINT (\fBROLLBACK_TO_SAVEPOINT\fR(7))\&.) Destroying a savepoint when it is no longer needed allows the system to reclaim some resources earlier than transaction end\&. +.PP +\fBRELEASE SAVEPOINT\fR +also destroys all savepoints that were established after the named savepoint was established\&. +.SH "PARAMETERS" +.PP +\fIsavepoint_name\fR +.RS 4 +The name of the savepoint to destroy\&. +.RE +.SH "NOTES" +.PP +Specifying a savepoint name that was not previously defined is an error\&. +.PP +It is not possible to release a savepoint when the transaction is in an aborted state\&. +.PP +If multiple savepoints have the same name, only the most recently defined unreleased one is released\&. Repeated commands will release progressively older savepoints\&. +.SH "EXAMPLES" +.PP +To establish and later destroy a savepoint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; + INSERT INTO table1 VALUES (3); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (4); + RELEASE SAVEPOINT my_savepoint; +COMMIT; +.fi +.if n \{\ +.RE +.\} +.sp +The above transaction will insert both 3 and 4\&. +.SH "COMPATIBILITY" +.PP +This command conforms to the +SQL +standard\&. The standard specifies that the key word +SAVEPOINT +is mandatory, but +PostgreSQL +allows it to be omitted\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), \fBROLLBACK\fR(7), ROLLBACK TO SAVEPOINT (\fBROLLBACK_TO_SAVEPOINT\fR(7)), \fBSAVEPOINT\fR(7) diff --git a/doc/src/sgml/man7/RESET.7 b/doc/src/sgml/man7/RESET.7 new file mode 100644 index 0000000..7d0cb8d --- /dev/null +++ b/doc/src/sgml/man7/RESET.7 @@ -0,0 +1,107 @@ +'\" t +.\" Title: RESET +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "RESET" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +RESET \- restore the value of a run\-time parameter to the default value +.SH "SYNOPSIS" +.sp +.nf +RESET \fIconfiguration_parameter\fR +RESET ALL +.fi +.SH "DESCRIPTION" +.PP +\fBRESET\fR +restores run\-time parameters to their default values\&. +\fBRESET\fR +is an alternative spelling for +.sp +.if n \{\ +.RS 4 +.\} +.nf +SET \fIconfiguration_parameter\fR TO DEFAULT +.fi +.if n \{\ +.RE +.\} +.sp +Refer to +\fBSET\fR(7) +for details\&. +.PP +The default value is defined as the value that the parameter would have had, if no +\fBSET\fR +had ever been issued for it in the current session\&. The actual source of this value might be a compiled\-in default, the configuration file, command\-line options, or per\-database or per\-user default settings\&. This is subtly different from defining it as +\(lqthe value that the parameter had at session start\(rq, because if the value came from the configuration file, it will be reset to whatever is specified by the configuration file now\&. See +Chapter\ \&20 +for details\&. +.PP +The transactional behavior of +\fBRESET\fR +is the same as +\fBSET\fR: its effects will be undone by transaction rollback\&. +.SH "PARAMETERS" +.PP +\fIconfiguration_parameter\fR +.RS 4 +Name of a settable run\-time parameter\&. Available parameters are documented in +Chapter\ \&20 +and on the +\fBSET\fR(7) +reference page\&. +.RE +.PP +ALL +.RS 4 +Resets all settable run\-time parameters to default values\&. +.RE +.SH "EXAMPLES" +.PP +Set the +\fItimezone\fR +configuration variable to its default value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +RESET timezone; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBRESET\fR +is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +\fBSET\fR(7), \fBSHOW\fR(7) diff --git a/doc/src/sgml/man7/REVOKE.7 b/doc/src/sgml/man7/REVOKE.7 new file mode 100644 index 0000000..34d702f --- /dev/null +++ b/doc/src/sgml/man7/REVOKE.7 @@ -0,0 +1,314 @@ +'\" t +.\" Title: REVOKE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "REVOKE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +REVOKE \- remove access privileges +.SH "SYNOPSIS" +.sp +.nf +REVOKE [ GRANT OPTION FOR ] + { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON { [ TABLE ] \fItable_name\fR [, \&.\&.\&.] + | ALL TABLES IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] } + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { SELECT | INSERT | UPDATE | REFERENCES } ( \fIcolumn_name\fR [, \&.\&.\&.] ) + [, \&.\&.\&.] | ALL [ PRIVILEGES ] ( \fIcolumn_name\fR [, \&.\&.\&.] ) } + ON [ TABLE ] \fItable_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { USAGE | SELECT | UPDATE } + [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON { SEQUENCE \fIsequence_name\fR [, \&.\&.\&.] + | ALL SEQUENCES IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] } + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { CREATE | CONNECT | TEMPORARY | TEMP } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON DATABASE \fIdatabase_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON DOMAIN \fIdomain_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON FOREIGN DATA WRAPPER \fIfdw_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON FOREIGN SERVER \fIserver_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { EXECUTE | ALL [ PRIVILEGES ] } + ON { { FUNCTION | PROCEDURE | ROUTINE } \fIfunction_name\fR [ ( [ [ \fIargmode\fR ] [ \fIarg_name\fR ] \fIarg_type\fR [, \&.\&.\&.] ] ) ] [, \&.\&.\&.] + | ALL { FUNCTIONS | PROCEDURES | ROUTINES } IN SCHEMA \fIschema_name\fR [, \&.\&.\&.] } + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON LANGUAGE \fIlang_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { SELECT | UPDATE } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON LARGE OBJECT \fIloid\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { SET | ALTER SYSTEM } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON PARAMETER \fIconfiguration_parameter\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { { CREATE | USAGE } [, \&.\&.\&.] | ALL [ PRIVILEGES ] } + ON SCHEMA \fIschema_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { CREATE | ALL [ PRIVILEGES ] } + ON TABLESPACE \fItablespace_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ GRANT OPTION FOR ] + { USAGE | ALL [ PRIVILEGES ] } + ON TYPE \fItype_name\fR [, \&.\&.\&.] + FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +REVOKE [ ADMIN OPTION FOR ] + \fIrole_name\fR [, \&.\&.\&.] FROM \fIrole_specification\fR [, \&.\&.\&.] + [ GRANTED BY \fIrole_specification\fR ] + [ CASCADE | RESTRICT ] + +where \fIrole_specification\fR can be: + + [ GROUP ] \fIrole_name\fR + | PUBLIC + | CURRENT_ROLE + | CURRENT_USER + | SESSION_USER +.fi +.SH "DESCRIPTION" +.PP +The +\fBREVOKE\fR +command revokes previously granted privileges from one or more roles\&. The key word +PUBLIC +refers to the implicitly defined group of all roles\&. +.PP +See the description of the +\fBGRANT\fR +command for the meaning of the privilege types\&. +.PP +Note that any particular role will have the sum of privileges granted directly to it, privileges granted to any role it is presently a member of, and privileges granted to +PUBLIC\&. Thus, for example, revoking +SELECT +privilege from +PUBLIC +does not necessarily mean that all roles have lost +SELECT +privilege on the object: those who have it granted directly or via another role will still have it\&. Similarly, revoking +SELECT +from a user might not prevent that user from using +SELECT +if +PUBLIC +or another membership role still has +SELECT +rights\&. +.PP +If +GRANT OPTION FOR +is specified, only the grant option for the privilege is revoked, not the privilege itself\&. Otherwise, both the privilege and the grant option are revoked\&. +.PP +If a user holds a privilege with grant option and has granted it to other users then the privileges held by those other users are called dependent privileges\&. If the privilege or the grant option held by the first user is being revoked and dependent privileges exist, those dependent privileges are also revoked if +CASCADE +is specified; if it is not, the revoke action will fail\&. This recursive revocation only affects privileges that were granted through a chain of users that is traceable to the user that is the subject of this +REVOKE +command\&. Thus, the affected users might effectively keep the privilege if it was also granted through other users\&. +.PP +When revoking privileges on a table, the corresponding column privileges (if any) are automatically revoked on each column of the table, as well\&. On the other hand, if a role has been granted privileges on a table, then revoking the same privileges from individual columns will have no effect\&. +.PP +When revoking membership in a role, +GRANT OPTION +is instead called +ADMIN OPTION, but the behavior is similar\&. This form of the command also allows a +GRANTED BY +option, but that option is currently ignored (except for checking the existence of the named role)\&. Note also that this form of the command does not allow the noise word +GROUP +in +\fIrole_specification\fR\&. +.SH "NOTES" +.PP +A user can only revoke privileges that were granted directly by that user\&. If, for example, user A has granted a privilege with grant option to user B, and user B has in turn granted it to user C, then user A cannot revoke the privilege directly from C\&. Instead, user A could revoke the grant option from user B and use the +CASCADE +option so that the privilege is in turn revoked from user C\&. For another example, if both A and B have granted the same privilege to C, A can revoke their own grant but not B\*(Aqs grant, so C will still effectively have the privilege\&. +.PP +When a non\-owner of an object attempts to +\fBREVOKE\fR +privileges on the object, the command will fail outright if the user has no privileges whatsoever on the object\&. As long as some privilege is available, the command will proceed, but it will revoke only those privileges for which the user has grant options\&. The +\fBREVOKE ALL PRIVILEGES\fR +forms will issue a warning message if no grant options are held, while the other forms will issue a warning if grant options for any of the privileges specifically named in the command are not held\&. (In principle these statements apply to the object owner as well, but since the owner is always treated as holding all grant options, the cases can never occur\&.) +.PP +If a superuser chooses to issue a +\fBGRANT\fR +or +\fBREVOKE\fR +command, the command is performed as though it were issued by the owner of the affected object\&. Since all privileges ultimately come from the object owner (possibly indirectly via chains of grant options), it is possible for a superuser to revoke all privileges, but this might require use of +CASCADE +as stated above\&. +.PP +\fBREVOKE\fR +can also be done by a role that is not the owner of the affected object, but is a member of the role that owns the object, or is a member of a role that holds privileges +WITH GRANT OPTION +on the object\&. In this case the command is performed as though it were issued by the containing role that actually owns the object or holds the privileges +WITH GRANT OPTION\&. For example, if table +t1 +is owned by role +g1, of which role +u1 +is a member, then +u1 +can revoke privileges on +t1 +that are recorded as being granted by +g1\&. This would include grants made by +u1 +as well as by other members of role +g1\&. +.PP +If the role executing +\fBREVOKE\fR +holds privileges indirectly via more than one role membership path, it is unspecified which containing role will be used to perform the command\&. In such cases it is best practice to use +\fBSET ROLE\fR +to become the specific role you want to do the +\fBREVOKE\fR +as\&. Failure to do so might lead to revoking privileges other than the ones you intended, or not revoking anything at all\&. +.PP +See +Section\ \&5.7 +for more information about specific privilege types, as well as how to inspect objects\*(Aq privileges\&. +.SH "EXAMPLES" +.PP +Revoke insert privilege for the public on table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REVOKE INSERT ON films FROM PUBLIC; +.fi +.if n \{\ +.RE +.\} +.PP +Revoke all privileges from user +manuel +on view +kinds: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REVOKE ALL PRIVILEGES ON kinds FROM manuel; +.fi +.if n \{\ +.RE +.\} +.sp +Note that this actually means +\(lqrevoke all privileges that I granted\(rq\&. +.PP +Revoke membership in role +admins +from user +joe: +.sp +.if n \{\ +.RS 4 +.\} +.nf +REVOKE admins FROM joe; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The compatibility notes of the +\fBGRANT\fR +command apply analogously to +\fBREVOKE\fR\&. The keyword +RESTRICT +or +CASCADE +is required according to the standard, but +PostgreSQL +assumes +RESTRICT +by default\&. +.SH "SEE ALSO" +\fBGRANT\fR(7), ALTER DEFAULT PRIVILEGES (\fBALTER_DEFAULT_PRIVILEGES\fR(7)) diff --git a/doc/src/sgml/man7/ROLLBACK.7 b/doc/src/sgml/man7/ROLLBACK.7 new file mode 100644 index 0000000..d7048cf --- /dev/null +++ b/doc/src/sgml/man7/ROLLBACK.7 @@ -0,0 +1,89 @@ +'\" t +.\" Title: ROLLBACK +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ROLLBACK" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ROLLBACK \- abort the current transaction +.SH "SYNOPSIS" +.sp +.nf +ROLLBACK [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] +.fi +.SH "DESCRIPTION" +.PP +\fBROLLBACK\fR +rolls back the current transaction and causes all the updates made by the transaction to be discarded\&. +.SH "PARAMETERS" +.PP +WORK +.br +TRANSACTION +.RS 4 +Optional key words\&. They have no effect\&. +.RE +.PP +AND CHAIN +.RS 4 +If +AND CHAIN +is specified, a new transaction is immediately started with the same transaction characteristics (see +SET TRANSACTION (\fBSET_TRANSACTION\fR(7))) as the just finished one\&. Otherwise, no new transaction is started\&. +.RE +.SH "NOTES" +.PP +Use +\fBCOMMIT\fR +to successfully terminate a transaction\&. +.PP +Issuing +\fBROLLBACK\fR +outside of a transaction block emits a warning and otherwise has no effect\&. +\fBROLLBACK AND CHAIN\fR +outside of a transaction block is an error\&. +.SH "EXAMPLES" +.PP +To abort all changes: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ROLLBACK; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The command +\fBROLLBACK\fR +conforms to the SQL standard\&. The form +ROLLBACK TRANSACTION +is a PostgreSQL extension\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), ROLLBACK TO SAVEPOINT (\fBROLLBACK_TO_SAVEPOINT\fR(7)) diff --git a/doc/src/sgml/man7/ROLLBACK_PREPARED.7 b/doc/src/sgml/man7/ROLLBACK_PREPARED.7 new file mode 100644 index 0000000..c6d7dc5 --- /dev/null +++ b/doc/src/sgml/man7/ROLLBACK_PREPARED.7 @@ -0,0 +1,77 @@ +'\" t +.\" Title: ROLLBACK PREPARED +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ROLLBACK PREPARED" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ROLLBACK_PREPARED \- cancel a transaction that was earlier prepared for two\-phase commit +.SH "SYNOPSIS" +.sp +.nf +ROLLBACK PREPARED \fItransaction_id\fR +.fi +.SH "DESCRIPTION" +.PP +\fBROLLBACK PREPARED\fR +rolls back a transaction that is in prepared state\&. +.SH "PARAMETERS" +.PP +\fItransaction_id\fR +.RS 4 +The transaction identifier of the transaction that is to be rolled back\&. +.RE +.SH "NOTES" +.PP +To roll back a prepared transaction, you must be either the same user that executed the transaction originally, or a superuser\&. But you do not have to be in the same session that executed the transaction\&. +.PP +This command cannot be executed inside a transaction block\&. The prepared transaction is rolled back immediately\&. +.PP +All currently available prepared transactions are listed in the +pg_prepared_xacts +system view\&. +.SH "EXAMPLES" +.PP +Roll back the transaction identified by the transaction identifier +foobar: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ROLLBACK PREPARED \*(Aqfoobar\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +\fBROLLBACK PREPARED\fR +is a +PostgreSQL +extension\&. It is intended for use by external transaction management systems, some of which are covered by standards (such as X/Open XA), but the SQL side of those systems is not standardized\&. +.SH "SEE ALSO" +PREPARE TRANSACTION (\fBPREPARE_TRANSACTION\fR(7)), COMMIT PREPARED (\fBCOMMIT_PREPARED\fR(7)) diff --git a/doc/src/sgml/man7/ROLLBACK_TO_SAVEPOINT.7 b/doc/src/sgml/man7/ROLLBACK_TO_SAVEPOINT.7 new file mode 100644 index 0000000..cb7e747 --- /dev/null +++ b/doc/src/sgml/man7/ROLLBACK_TO_SAVEPOINT.7 @@ -0,0 +1,132 @@ +'\" t +.\" Title: ROLLBACK TO SAVEPOINT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "ROLLBACK TO SAVEPOINT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +ROLLBACK_TO_SAVEPOINT \- roll back to a savepoint +.SH "SYNOPSIS" +.sp +.nf +ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] \fIsavepoint_name\fR +.fi +.SH "DESCRIPTION" +.PP +Roll back all commands that were executed after the savepoint was established\&. The savepoint remains valid and can be rolled back to again later, if needed\&. +.PP +\fBROLLBACK TO SAVEPOINT\fR +implicitly destroys all savepoints that were established after the named savepoint\&. +.SH "PARAMETERS" +.PP +\fIsavepoint_name\fR +.RS 4 +The savepoint to roll back to\&. +.RE +.SH "NOTES" +.PP +Use +\fBRELEASE SAVEPOINT\fR +to destroy a savepoint without discarding the effects of commands executed after it was established\&. +.PP +Specifying a savepoint name that has not been established is an error\&. +.PP +Cursors have somewhat non\-transactional behavior with respect to savepoints\&. Any cursor that is opened inside a savepoint will be closed when the savepoint is rolled back\&. If a previously opened cursor is affected by a +\fBFETCH\fR +or +\fBMOVE\fR +command inside a savepoint that is later rolled back, the cursor remains at the position that +\fBFETCH\fR +left it pointing to (that is, the cursor motion caused by +\fBFETCH\fR +is not rolled back)\&. Closing a cursor is not undone by rolling back, either\&. However, other side\-effects caused by the cursor\*(Aqs query (such as side\-effects of volatile functions called by the query) +\fIare\fR +rolled back if they occur during a savepoint that is later rolled back\&. A cursor whose execution causes a transaction to abort is put in a cannot\-execute state, so while the transaction can be restored using +\fBROLLBACK TO SAVEPOINT\fR, the cursor can no longer be used\&. +.SH "EXAMPLES" +.PP +To undo the effects of the commands executed after +my_savepoint +was established: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ROLLBACK TO SAVEPOINT my_savepoint; +.fi +.if n \{\ +.RE +.\} +.PP +Cursor positions are not affected by savepoint rollback: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; + +DECLARE foo CURSOR FOR SELECT 1 UNION SELECT 2; + +SAVEPOINT foo; + +FETCH 1 FROM foo; + ?column? +\-\-\-\-\-\-\-\-\-\- + 1 + +ROLLBACK TO SAVEPOINT foo; + +FETCH 1 FROM foo; + ?column? +\-\-\-\-\-\-\-\-\-\- + 2 + +COMMIT; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +SQL +standard specifies that the key word +SAVEPOINT +is mandatory, but +PostgreSQL +and +Oracle +allow it to be omitted\&. SQL allows only +WORK, not +TRANSACTION, as a noise word after +ROLLBACK\&. Also, SQL has an optional clause +AND [ NO ] CHAIN +which is not currently supported by +PostgreSQL\&. Otherwise, this command conforms to the SQL standard\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), RELEASE SAVEPOINT (\fBRELEASE_SAVEPOINT\fR(7)), \fBROLLBACK\fR(7), \fBSAVEPOINT\fR(7) diff --git a/doc/src/sgml/man7/SAVEPOINT.7 b/doc/src/sgml/man7/SAVEPOINT.7 new file mode 100644 index 0000000..87bbbe4 --- /dev/null +++ b/doc/src/sgml/man7/SAVEPOINT.7 @@ -0,0 +1,141 @@ +'\" t +.\" Title: SAVEPOINT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SAVEPOINT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SAVEPOINT \- define a new savepoint within the current transaction +.SH "SYNOPSIS" +.sp +.nf +SAVEPOINT \fIsavepoint_name\fR +.fi +.SH "DESCRIPTION" +.PP +\fBSAVEPOINT\fR +establishes a new savepoint within the current transaction\&. +.PP +A savepoint is a special mark inside a transaction that allows all commands that are executed after it was established to be rolled back, restoring the transaction state to what it was at the time of the savepoint\&. +.SH "PARAMETERS" +.PP +\fIsavepoint_name\fR +.RS 4 +The name to give to the new savepoint\&. If savepoints with the same name already exist, they will be inaccessible until newer identically\-named savepoints are released\&. +.RE +.SH "NOTES" +.PP +Use +\fBROLLBACK TO\fR +to rollback to a savepoint\&. Use +\fBRELEASE SAVEPOINT\fR +to destroy a savepoint, keeping the effects of commands executed after it was established\&. +.PP +Savepoints can only be established when inside a transaction block\&. There can be multiple savepoints defined within a transaction\&. +.SH "EXAMPLES" +.PP +To establish a savepoint and later undo the effects of all commands executed after it was established: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; + INSERT INTO table1 VALUES (1); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (2); + ROLLBACK TO SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (3); +COMMIT; +.fi +.if n \{\ +.RE +.\} +.sp +The above transaction will insert the values 1 and 3, but not 2\&. +.PP +To establish and later destroy a savepoint: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; + INSERT INTO table1 VALUES (3); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (4); + RELEASE SAVEPOINT my_savepoint; +COMMIT; +.fi +.if n \{\ +.RE +.\} +.sp +The above transaction will insert both 3 and 4\&. +.PP +To use a single savepoint name: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; + INSERT INTO table1 VALUES (1); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (2); + SAVEPOINT my_savepoint; + INSERT INTO table1 VALUES (3); + + \-\- rollback to the second savepoint + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; \-\- shows rows 1 and 2 + + \-\- release the second savepoint + RELEASE SAVEPOINT my_savepoint; + + \-\- rollback to the first savepoint + ROLLBACK TO SAVEPOINT my_savepoint; + SELECT * FROM table1; \-\- shows only row 1 +COMMIT; +.fi +.if n \{\ +.RE +.\} +.sp +The above transaction shows row 3 being rolled back first, then row 2\&. +.SH "COMPATIBILITY" +.PP +SQL requires a savepoint to be destroyed automatically when another savepoint with the same name is established\&. In +PostgreSQL, the old savepoint is kept, though only the more recent one will be used when rolling back or releasing\&. (Releasing the newer savepoint with +\fBRELEASE SAVEPOINT\fR +will cause the older one to again become accessible to +\fBROLLBACK TO SAVEPOINT\fR +and +\fBRELEASE SAVEPOINT\fR\&.) Otherwise, +\fBSAVEPOINT\fR +is fully SQL conforming\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), RELEASE SAVEPOINT (\fBRELEASE_SAVEPOINT\fR(7)), \fBROLLBACK\fR(7), ROLLBACK TO SAVEPOINT (\fBROLLBACK_TO_SAVEPOINT\fR(7)) diff --git a/doc/src/sgml/man7/SECURITY_LABEL.7 b/doc/src/sgml/man7/SECURITY_LABEL.7 new file mode 100644 index 0000000..c92fea0 --- /dev/null +++ b/doc/src/sgml/man7/SECURITY_LABEL.7 @@ -0,0 +1,198 @@ +'\" t +.\" Title: SECURITY LABEL +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SECURITY LABEL" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SECURITY_LABEL \- define or change a security label applied to an object +.SH "SYNOPSIS" +.sp +.nf +SECURITY LABEL [ FOR \fIprovider\fR ] ON +{ + TABLE \fIobject_name\fR | + COLUMN \fItable_name\fR\&.\fIcolumn_name\fR | + AGGREGATE \fIaggregate_name\fR ( \fIaggregate_signature\fR ) | + DATABASE \fIobject_name\fR | + DOMAIN \fIobject_name\fR | + EVENT TRIGGER \fIobject_name\fR | + FOREIGN TABLE \fIobject_name\fR + FUNCTION \fIfunction_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + LARGE OBJECT \fIlarge_object_oid\fR | + MATERIALIZED VIEW \fIobject_name\fR | + [ PROCEDURAL ] LANGUAGE \fIobject_name\fR | + PROCEDURE \fIprocedure_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + PUBLICATION \fIobject_name\fR | + ROLE \fIobject_name\fR | + ROUTINE \fIroutine_name\fR [ ( [ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [, \&.\&.\&.] ] ) ] | + SCHEMA \fIobject_name\fR | + SEQUENCE \fIobject_name\fR | + SUBSCRIPTION \fIobject_name\fR | + TABLESPACE \fIobject_name\fR | + TYPE \fIobject_name\fR | + VIEW \fIobject_name\fR +} IS { \fIstring_literal\fR | NULL } + +where \fIaggregate_signature\fR is: + +* | +[ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] | +[ [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] ] ORDER BY [ \fIargmode\fR ] [ \fIargname\fR ] \fIargtype\fR [ , \&.\&.\&. ] +.fi +.SH "DESCRIPTION" +.PP +\fBSECURITY LABEL\fR +applies a security label to a database object\&. An arbitrary number of security labels, one per label provider, can be associated with a given database object\&. Label providers are loadable modules which register themselves by using the function +\fBregister_label_provider\fR\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +\fBregister_label_provider\fR +is not an SQL function; it can only be called from C code loaded into the backend\&. +.sp .5v +.RE +.PP +The label provider determines whether a given label is valid and whether it is permissible to assign that label to a given object\&. The meaning of a given label is likewise at the discretion of the label provider\&. +PostgreSQL +places no restrictions on whether or how a label provider must interpret security labels; it merely provides a mechanism for storing them\&. In practice, this facility is intended to allow integration with label\-based mandatory access control (MAC) systems such as +SELinux\&. Such systems make all access control decisions based on object labels, rather than traditional discretionary access control (DAC) concepts such as users and groups\&. +.SH "PARAMETERS" +.PP +\fIobject_name\fR +.br +\fItable_name\&.column_name\fR +.br +\fIaggregate_name\fR +.br +\fIfunction_name\fR +.br +\fIprocedure_name\fR +.br +\fIroutine_name\fR +.RS 4 +The name of the object to be labeled\&. Names of objects that reside in schemas (tables, functions, etc\&.) can be schema\-qualified\&. +.RE +.PP +\fIprovider\fR +.RS 4 +The name of the provider with which this label is to be associated\&. The named provider must be loaded and must consent to the proposed labeling operation\&. If exactly one provider is loaded, the provider name may be omitted for brevity\&. +.RE +.PP +\fIargmode\fR +.RS 4 +The mode of a function, procedure, or aggregate argument: +IN, +OUT, +INOUT, or +VARIADIC\&. If omitted, the default is +IN\&. Note that +\fBSECURITY LABEL\fR +does not actually pay any attention to +OUT +arguments, since only the input arguments are needed to determine the function\*(Aqs identity\&. So it is sufficient to list the +IN, +INOUT, and +VARIADIC +arguments\&. +.RE +.PP +\fIargname\fR +.RS 4 +The name of a function, procedure, or aggregate argument\&. Note that +\fBSECURITY LABEL\fR +does not actually pay any attention to argument names, since only the argument data types are needed to determine the function\*(Aqs identity\&. +.RE +.PP +\fIargtype\fR +.RS 4 +The data type of a function, procedure, or aggregate argument\&. +.RE +.PP +\fIlarge_object_oid\fR +.RS 4 +The OID of the large object\&. +.RE +.PP +PROCEDURAL +.RS 4 +This is a noise word\&. +.RE +.PP +\fIstring_literal\fR +.RS 4 +The new setting of the security label, written as a string literal\&. +.RE +.PP +NULL +.RS 4 +Write +NULL +to drop the security label\&. +.RE +.SH "EXAMPLES" +.PP +The following example shows how the security label of a table could be set or changed: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SECURITY LABEL FOR selinux ON TABLE mytable IS \*(Aqsystem_u:object_r:sepgsql_table_t:s0\*(Aq; +.fi +.if n \{\ +.RE +.\} +.sp +To remove the label: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SECURITY LABEL FOR selinux ON TABLE mytable IS NULL; +.fi +.if n \{\ +.RE +.\} +.sp +.SH "COMPATIBILITY" +.PP +There is no +\fBSECURITY LABEL\fR +command in the SQL standard\&. +.SH "SEE ALSO" +sepgsql, src/test/modules/dummy_seclabel diff --git a/doc/src/sgml/man7/SELECT.7 b/doc/src/sgml/man7/SELECT.7 new file mode 100644 index 0000000..2ee94fc --- /dev/null +++ b/doc/src/sgml/man7/SELECT.7 @@ -0,0 +1,2526 @@ +'\" t +.\" Title: SELECT +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SELECT" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SELECT, TABLE, WITH \- retrieve rows from a table or view +.SH "SYNOPSIS" +.sp +.nf +[ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ] +SELECT [ ALL | DISTINCT [ ON ( \fIexpression\fR [, \&.\&.\&.] ) ] ] + [ * | \fIexpression\fR [ [ AS ] \fIoutput_name\fR ] [, \&.\&.\&.] ] + [ FROM \fIfrom_item\fR [, \&.\&.\&.] ] + [ WHERE \fIcondition\fR ] + [ GROUP BY [ ALL | DISTINCT ] \fIgrouping_element\fR [, \&.\&.\&.] ] + [ HAVING \fIcondition\fR ] + [ WINDOW \fIwindow_name\fR AS ( \fIwindow_definition\fR ) [, \&.\&.\&.] ] + [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] \fIselect\fR ] + [ ORDER BY \fIexpression\fR [ ASC | DESC | USING \fIoperator\fR ] [ NULLS { FIRST | LAST } ] [, \&.\&.\&.] ] + [ LIMIT { \fIcount\fR | ALL } ] + [ OFFSET \fIstart\fR [ ROW | ROWS ] ] + [ FETCH { FIRST | NEXT } [ \fIcount\fR ] { ROW | ROWS } { ONLY | WITH TIES } ] + [ FOR { UPDATE | NO KEY UPDATE | SHARE | KEY SHARE } [ OF \fItable_name\fR [, \&.\&.\&.] ] [ NOWAIT | SKIP LOCKED ] [\&.\&.\&.] ] + +where \fIfrom_item\fR can be one of: + + [ ONLY ] \fItable_name\fR [ * ] [ [ AS ] \fIalias\fR [ ( \fIcolumn_alias\fR [, \&.\&.\&.] ) ] ] + [ TABLESAMPLE \fIsampling_method\fR ( \fIargument\fR [, \&.\&.\&.] ) [ REPEATABLE ( \fIseed\fR ) ] ] + [ LATERAL ] ( \fIselect\fR ) [ AS ] \fIalias\fR [ ( \fIcolumn_alias\fR [, \&.\&.\&.] ) ] + \fIwith_query_name\fR [ [ AS ] \fIalias\fR [ ( \fIcolumn_alias\fR [, \&.\&.\&.] ) ] ] + [ LATERAL ] \fIfunction_name\fR ( [ \fIargument\fR [, \&.\&.\&.] ] ) + [ WITH ORDINALITY ] [ [ AS ] \fIalias\fR [ ( \fIcolumn_alias\fR [, \&.\&.\&.] ) ] ] + [ LATERAL ] \fIfunction_name\fR ( [ \fIargument\fR [, \&.\&.\&.] ] ) [ AS ] \fIalias\fR ( \fIcolumn_definition\fR [, \&.\&.\&.] ) + [ LATERAL ] \fIfunction_name\fR ( [ \fIargument\fR [, \&.\&.\&.] ] ) AS ( \fIcolumn_definition\fR [, \&.\&.\&.] ) + [ LATERAL ] ROWS FROM( \fIfunction_name\fR ( [ \fIargument\fR [, \&.\&.\&.] ] ) [ AS ( \fIcolumn_definition\fR [, \&.\&.\&.] ) ] [, \&.\&.\&.] ) + [ WITH ORDINALITY ] [ [ AS ] \fIalias\fR [ ( \fIcolumn_alias\fR [, \&.\&.\&.] ) ] ] + \fIfrom_item\fR \fIjoin_type\fR \fIfrom_item\fR { ON \fIjoin_condition\fR | USING ( \fIjoin_column\fR [, \&.\&.\&.] ) [ AS \fIjoin_using_alias\fR ] } + \fIfrom_item\fR NATURAL \fIjoin_type\fR \fIfrom_item\fR + \fIfrom_item\fR CROSS JOIN \fIfrom_item\fR + +and \fIgrouping_element\fR can be one of: + + ( ) + \fIexpression\fR + ( \fIexpression\fR [, \&.\&.\&.] ) + ROLLUP ( { \fIexpression\fR | ( \fIexpression\fR [, \&.\&.\&.] ) } [, \&.\&.\&.] ) + CUBE ( { \fIexpression\fR | ( \fIexpression\fR [, \&.\&.\&.] ) } [, \&.\&.\&.] ) + GROUPING SETS ( \fIgrouping_element\fR [, \&.\&.\&.] ) + +and \fIwith_query\fR is: + + \fIwith_query_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] AS [ [ NOT ] MATERIALIZED ] ( \fIselect\fR | \fIvalues\fR | \fIinsert\fR | \fIupdate\fR | \fIdelete\fR ) + [ SEARCH { BREADTH | DEPTH } FIRST BY \fIcolumn_name\fR [, \&.\&.\&.] SET \fIsearch_seq_col_name\fR ] + [ CYCLE \fIcolumn_name\fR [, \&.\&.\&.] SET \fIcycle_mark_col_name\fR [ TO \fIcycle_mark_value\fR DEFAULT \fIcycle_mark_default\fR ] USING \fIcycle_path_col_name\fR ] + +TABLE [ ONLY ] \fItable_name\fR [ * ] +.fi +.SH "DESCRIPTION" +.PP +\fBSELECT\fR +retrieves rows from zero or more tables\&. The general processing of +\fBSELECT\fR +is as follows: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +All queries in the +WITH +list are computed\&. These effectively serve as temporary tables that can be referenced in the +FROM +list\&. A +WITH +query that is referenced more than once in +FROM +is computed only once, unless specified otherwise with +NOT MATERIALIZED\&. (See +WITH Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +All elements in the +FROM +list are computed\&. (Each element in the +FROM +list is a real or virtual table\&.) If more than one element is specified in the +FROM +list, they are cross\-joined together\&. (See +FROM Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +If the +WHERE +clause is specified, all rows that do not satisfy the condition are eliminated from the output\&. (See +WHERE Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 4." 4.2 +.\} +If the +GROUP BY +clause is specified, or if there are aggregate function calls, the output is combined into groups of rows that match on one or more values, and the results of aggregate functions are computed\&. If the +HAVING +clause is present, it eliminates groups that do not satisfy the given condition\&. (See +GROUP BY Clause +and +HAVING Clause +below\&.) Although query output columns are nominally computed in the next step, they can also be referenced (by name or ordinal number) in the +GROUP BY +clause\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 5." 4.2 +.\} +The actual output rows are computed using the +\fBSELECT\fR +output expressions for each selected row or row group\&. (See +SELECT List +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 6." 4.2 +.\} +SELECT DISTINCT +eliminates duplicate rows from the result\&. +SELECT DISTINCT ON +eliminates rows that match on all the specified expressions\&. +SELECT ALL +(the default) will return all candidate rows, including duplicates\&. (See +DISTINCT Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 7.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 7." 4.2 +.\} +Using the operators +UNION, +INTERSECT, and +EXCEPT, the output of more than one +\fBSELECT\fR +statement can be combined to form a single result set\&. The +UNION +operator returns all rows that are in one or both of the result sets\&. The +INTERSECT +operator returns all rows that are strictly in both result sets\&. The +EXCEPT +operator returns the rows that are in the first result set but not in the second\&. In all three cases, duplicate rows are eliminated unless +ALL +is specified\&. The noise word +DISTINCT +can be added to explicitly specify eliminating duplicate rows\&. Notice that +DISTINCT +is the default behavior here, even though +ALL +is the default for +\fBSELECT\fR +itself\&. (See +UNION Clause, +INTERSECT Clause, and +EXCEPT Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 8.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 8." 4.2 +.\} +If the +ORDER BY +clause is specified, the returned rows are sorted in the specified order\&. If +ORDER BY +is not given, the rows are returned in whatever order the system finds fastest to produce\&. (See +ORDER BY Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 9.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 9." 4.2 +.\} +If the +LIMIT +(or +FETCH FIRST) or +OFFSET +clause is specified, the +\fBSELECT\fR +statement only returns a subset of the result rows\&. (See +LIMIT Clause +below\&.) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'10.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP "10." 4.2 +.\} +If +FOR UPDATE, +FOR NO KEY UPDATE, +FOR SHARE +or +FOR KEY SHARE +is specified, the +\fBSELECT\fR +statement locks the selected rows against concurrent updates\&. (See +The Locking Clause +below\&.) +.RE +.PP +You must have +SELECT +privilege on each column used in a +\fBSELECT\fR +command\&. The use of +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +or +FOR KEY SHARE +requires +UPDATE +privilege as well (for at least one column of each table so selected)\&. +.SH "PARAMETERS" +.SS "WITH Clause" +.PP +The +WITH +clause allows you to specify one or more subqueries that can be referenced by name in the primary query\&. The subqueries effectively act as temporary tables or views for the duration of the primary query\&. Each subquery can be a +\fBSELECT\fR, +\fBTABLE\fR, +\fBVALUES\fR, +\fBINSERT\fR, +\fBUPDATE\fR +or +\fBDELETE\fR +statement\&. When writing a data\-modifying statement (\fBINSERT\fR, +\fBUPDATE\fR +or +\fBDELETE\fR) in +WITH, it is usual to include a +RETURNING +clause\&. It is the output of +RETURNING, +\fInot\fR +the underlying table that the statement modifies, that forms the temporary table that is read by the primary query\&. If +RETURNING +is omitted, the statement is still executed, but it produces no output so it cannot be referenced as a table by the primary query\&. +.PP +A name (without schema qualification) must be specified for each +WITH +query\&. Optionally, a list of column names can be specified; if this is omitted, the column names are inferred from the subquery\&. +.PP +If +RECURSIVE +is specified, it allows a +\fBSELECT\fR +subquery to reference itself by name\&. Such a subquery must have the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fInon_recursive_term\fR UNION [ ALL | DISTINCT ] \fIrecursive_term\fR +.fi +.if n \{\ +.RE +.\} +.sp +where the recursive self\-reference must appear on the right\-hand side of the +UNION\&. Only one recursive self\-reference is permitted per query\&. Recursive data\-modifying statements are not supported, but you can use the results of a recursive +\fBSELECT\fR +query in a data\-modifying statement\&. See +Section\ \&7.8 +for an example\&. +.PP +Another effect of +RECURSIVE +is that +WITH +queries need not be ordered: a query can reference another one that is later in the list\&. (However, circular references, or mutual recursion, are not implemented\&.) Without +RECURSIVE, +WITH +queries can only reference sibling +WITH +queries that are earlier in the +WITH +list\&. +.PP +When there are multiple queries in the +WITH +clause, +RECURSIVE +should be written only once, immediately after +WITH\&. It applies to all queries in the +WITH +clause, though it has no effect on queries that do not use recursion or forward references\&. +.PP +The optional +SEARCH +clause computes a +search sequence column +that can be used for ordering the results of a recursive query in either breadth\-first or depth\-first order\&. The supplied column name list specifies the row key that is to be used for keeping track of visited rows\&. A column named +\fIsearch_seq_col_name\fR +will be added to the result column list of the +WITH +query\&. This column can be ordered by in the outer query to achieve the respective ordering\&. See +Section\ \&7.8.2.1 +for examples\&. +.PP +The optional +CYCLE +clause is used to detect cycles in recursive queries\&. The supplied column name list specifies the row key that is to be used for keeping track of visited rows\&. A column named +\fIcycle_mark_col_name\fR +will be added to the result column list of the +WITH +query\&. This column will be set to +\fIcycle_mark_value\fR +when a cycle has been detected, else to +\fIcycle_mark_default\fR\&. Furthermore, processing of the recursive union will stop when a cycle has been detected\&. +\fIcycle_mark_value\fR +and +\fIcycle_mark_default\fR +must be constants and they must be coercible to a common data type, and the data type must have an inequality operator\&. (The SQL standard requires that they be Boolean constants or character strings, but PostgreSQL does not require that\&.) By default, +TRUE +and +FALSE +(of type +boolean) are used\&. Furthermore, a column named +\fIcycle_path_col_name\fR +will be added to the result column list of the +WITH +query\&. This column is used internally for tracking visited rows\&. See +Section\ \&7.8.2.2 +for examples\&. +.PP +Both the +SEARCH +and the +CYCLE +clause are only valid for recursive +WITH +queries\&. The +\fIwith_query\fR +must be a +UNION +(or +UNION ALL) of two +SELECT +(or equivalent) commands (no nested +UNIONs)\&. If both clauses are used, the column added by the +SEARCH +clause appears before the columns added by the +CYCLE +clause\&. +.PP +The primary query and the +WITH +queries are all (notionally) executed at the same time\&. This implies that the effects of a data\-modifying statement in +WITH +cannot be seen from other parts of the query, other than by reading its +RETURNING +output\&. If two such data\-modifying statements attempt to modify the same row, the results are unspecified\&. +.PP +A key property of +WITH +queries is that they are normally evaluated only once per execution of the primary query, even if the primary query refers to them more than once\&. In particular, data\-modifying statements are guaranteed to be executed once and only once, regardless of whether the primary query reads all or any of their output\&. +.PP +However, a +WITH +query can be marked +NOT MATERIALIZED +to remove this guarantee\&. In that case, the +WITH +query can be folded into the primary query much as though it were a simple sub\-SELECT +in the primary query\*(Aqs +FROM +clause\&. This results in duplicate computations if the primary query refers to that +WITH +query more than once; but if each such use requires only a few rows of the +WITH +query\*(Aqs total output, +NOT MATERIALIZED +can provide a net savings by allowing the queries to be optimized jointly\&. +NOT MATERIALIZED +is ignored if it is attached to a +WITH +query that is recursive or is not side\-effect\-free (i\&.e\&., is not a plain +SELECT +containing no volatile functions)\&. +.PP +By default, a side\-effect\-free +WITH +query is folded into the primary query if it is used exactly once in the primary query\*(Aqs +FROM +clause\&. This allows joint optimization of the two query levels in situations where that should be semantically invisible\&. However, such folding can be prevented by marking the +WITH +query as +MATERIALIZED\&. That might be useful, for example, if the +WITH +query is being used as an optimization fence to prevent the planner from choosing a bad plan\&. +PostgreSQL +versions before v12 never did such folding, so queries written for older versions might rely on +WITH +to act as an optimization fence\&. +.PP +See +Section\ \&7.8 +for additional information\&. +.SS "FROM Clause" +.PP +The +FROM +clause specifies one or more source tables for the +\fBSELECT\fR\&. If multiple sources are specified, the result is the Cartesian product (cross join) of all the sources\&. But usually qualification conditions are added (via +WHERE) to restrict the returned rows to a small subset of the Cartesian product\&. +.PP +The +FROM +clause can contain the following elements: +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of an existing table or view\&. If +ONLY +is specified before the table name, only that table is scanned\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are scanned\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +\fIalias\fR +.RS 4 +A substitute name for the +FROM +item containing the alias\&. An alias is used for brevity or to eliminate ambiguity for self\-joins (where the same table is scanned multiple times)\&. When an alias is provided, it completely hides the actual name of the table or function; for example given +FROM foo AS f, the remainder of the +\fBSELECT\fR +must refer to this +FROM +item as +f +not +foo\&. If an alias is written, a column alias list can also be written to provide substitute names for one or more columns of the table\&. +.RE +.PP +TABLESAMPLE \fIsampling_method\fR ( \fIargument\fR [, \&.\&.\&.] ) [ REPEATABLE ( \fIseed\fR ) ] +.RS 4 +A +TABLESAMPLE +clause after a +\fItable_name\fR +indicates that the specified +\fIsampling_method\fR +should be used to retrieve a subset of the rows in that table\&. This sampling precedes the application of any other filters such as +WHERE +clauses\&. The standard +PostgreSQL +distribution includes two sampling methods, +BERNOULLI +and +SYSTEM, and other sampling methods can be installed in the database via extensions\&. +.sp +The +BERNOULLI +and +SYSTEM +sampling methods each accept a single +\fIargument\fR +which is the fraction of the table to sample, expressed as a percentage between 0 and 100\&. This argument can be any +real\-valued expression\&. (Other sampling methods might accept more or different arguments\&.) These two methods each return a randomly\-chosen sample of the table that will contain approximately the specified percentage of the table\*(Aqs rows\&. The +BERNOULLI +method scans the whole table and selects or ignores individual rows independently with the specified probability\&. The +SYSTEM +method does block\-level sampling with each block having the specified chance of being selected; all rows in each selected block are returned\&. The +SYSTEM +method is significantly faster than the +BERNOULLI +method when small sampling percentages are specified, but it may return a less\-random sample of the table as a result of clustering effects\&. +.sp +The optional +REPEATABLE +clause specifies a +\fIseed\fR +number or expression to use for generating random numbers within the sampling method\&. The seed value can be any non\-null floating\-point value\&. Two queries that specify the same seed and +\fIargument\fR +values will select the same sample of the table, if the table has not been changed meanwhile\&. But different seed values will usually produce different samples\&. If +REPEATABLE +is not given then a new random sample is selected for each query, based upon a system\-generated seed\&. Note that some add\-on sampling methods do not accept +REPEATABLE, and will always produce new samples on each use\&. +.RE +.PP +\fIselect\fR +.RS 4 +A sub\-\fBSELECT\fR +can appear in the +FROM +clause\&. This acts as though its output were created as a temporary table for the duration of this single +\fBSELECT\fR +command\&. Note that the sub\-\fBSELECT\fR +must be surrounded by parentheses, and an alias +\fImust\fR +be provided for it\&. A +\fBVALUES\fR +command can also be used here\&. +.RE +.PP +\fIwith_query_name\fR +.RS 4 +A +WITH +query is referenced by writing its name, just as though the query\*(Aqs name were a table name\&. (In fact, the +WITH +query hides any real table of the same name for the purposes of the primary query\&. If necessary, you can refer to a real table of the same name by schema\-qualifying the table\*(Aqs name\&.) An alias can be provided in the same way as for a table\&. +.RE +.PP +\fIfunction_name\fR +.RS 4 +Function calls can appear in the +FROM +clause\&. (This is especially useful for functions that return result sets, but any function can be used\&.) This acts as though the function\*(Aqs output were created as a temporary table for the duration of this single +\fBSELECT\fR +command\&. If the function\*(Aqs result type is composite (including the case of a function with multiple +OUT +parameters), each attribute becomes a separate column in the implicit table\&. +.sp +When the optional +\fBWITH ORDINALITY\fR +clause is added to the function call, an additional column of type +bigint +will be appended to the function\*(Aqs result column(s)\&. This column numbers the rows of the function\*(Aqs result set, starting from 1\&. By default, this column is named +ordinality\&. +.sp +An alias can be provided in the same way as for a table\&. If an alias is written, a column alias list can also be written to provide substitute names for one or more attributes of the function\*(Aqs composite return type, including the ordinality column if present\&. +.sp +Multiple function calls can be combined into a single +FROM\-clause item by surrounding them with +ROWS FROM( \&.\&.\&. )\&. The output of such an item is the concatenation of the first row from each function, then the second row from each function, etc\&. If some of the functions produce fewer rows than others, null values are substituted for the missing data, so that the total number of rows returned is always the same as for the function that produced the most rows\&. +.sp +If the function has been defined as returning the +record +data type, then an alias or the key word +AS +must be present, followed by a column definition list in the form +( \fIcolumn_name\fR \fIdata_type\fR [, \&.\&.\&. ])\&. The column definition list must match the actual number and types of columns returned by the function\&. +.sp +When using the +ROWS FROM( \&.\&.\&. ) +syntax, if one of the functions requires a column definition list, it\*(Aqs preferred to put the column definition list after the function call inside +ROWS FROM( \&.\&.\&. )\&. A column definition list can be placed after the +ROWS FROM( \&.\&.\&. ) +construct only if there\*(Aqs just a single function and no +WITH ORDINALITY +clause\&. +.sp +To use +ORDINALITY +together with a column definition list, you must use the +ROWS FROM( \&.\&.\&. ) +syntax and put the column definition list inside +ROWS FROM( \&.\&.\&. )\&. +.RE +.PP +\fIjoin_type\fR +.RS 4 +One of +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +[ INNER ] JOIN +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +LEFT [ OUTER ] JOIN +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +RIGHT [ OUTER ] JOIN +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +FULL [ OUTER ] JOIN +.RE +.sp +For the +INNER +and +OUTER +join types, a join condition must be specified, namely exactly one of +ON \fIjoin_condition\fR, +USING (\fIjoin_column\fR [, \&.\&.\&.]), or +NATURAL\&. See below for the meaning\&. +.sp +A +JOIN +clause combines two +FROM +items, which for convenience we will refer to as +\(lqtables\(rq, though in reality they can be any type of +FROM +item\&. Use parentheses if necessary to determine the order of nesting\&. In the absence of parentheses, +JOINs nest left\-to\-right\&. In any case +JOIN +binds more tightly than the commas separating +FROM\-list items\&. All the +JOIN +options are just a notational convenience, since they do nothing you couldn\*(Aqt do with plain +FROM +and +WHERE\&. +.sp +LEFT OUTER JOIN +returns all rows in the qualified Cartesian product (i\&.e\&., all combined rows that pass its join condition), plus one copy of each row in the left\-hand table for which there was no right\-hand row that passed the join condition\&. This left\-hand row is extended to the full width of the joined table by inserting null values for the right\-hand columns\&. Note that only the +JOIN +clause\*(Aqs own condition is considered while deciding which rows have matches\&. Outer conditions are applied afterwards\&. +.sp +Conversely, +RIGHT OUTER JOIN +returns all the joined rows, plus one row for each unmatched right\-hand row (extended with nulls on the left)\&. This is just a notational convenience, since you could convert it to a +LEFT OUTER JOIN +by switching the left and right tables\&. +.sp +FULL OUTER JOIN +returns all the joined rows, plus one row for each unmatched left\-hand row (extended with nulls on the right), plus one row for each unmatched right\-hand row (extended with nulls on the left)\&. +.RE +.PP +ON \fIjoin_condition\fR +.RS 4 +\fIjoin_condition\fR +is an expression resulting in a value of type +boolean +(similar to a +WHERE +clause) that specifies which rows in a join are considered to match\&. +.RE +.PP +USING ( \fIjoin_column\fR [, \&.\&.\&.] ) [ AS \fIjoin_using_alias\fR ] +.RS 4 +A clause of the form +USING ( a, b, \&.\&.\&. ) +is shorthand for +ON left_table\&.a = right_table\&.a AND left_table\&.b = right_table\&.b \&.\&.\&.\&. Also, +USING +implies that only one of each pair of equivalent columns will be included in the join output, not both\&. +.sp +If a +\fIjoin_using_alias\fR +name is specified, it provides a table alias for the join columns\&. Only the join columns listed in the +USING +clause are addressable by this name\&. Unlike a regular +\fIalias\fR, this does not hide the names of the joined tables from the rest of the query\&. Also unlike a regular +\fIalias\fR, you cannot write a column alias list \(em the output names of the join columns are the same as they appear in the +USING +list\&. +.RE +.PP +NATURAL +.RS 4 +NATURAL +is shorthand for a +USING +list that mentions all columns in the two tables that have matching names\&. If there are no common column names, +NATURAL +is equivalent to +ON TRUE\&. +.RE +.PP +CROSS JOIN +.RS 4 +CROSS JOIN +is equivalent to +INNER JOIN ON (TRUE), that is, no rows are removed by qualification\&. They produce a simple Cartesian product, the same result as you get from listing the two tables at the top level of +FROM, but restricted by the join condition (if any)\&. +.RE +.PP +LATERAL +.RS 4 +The +LATERAL +key word can precede a sub\-\fBSELECT\fR +FROM +item\&. This allows the sub\-\fBSELECT\fR +to refer to columns of +FROM +items that appear before it in the +FROM +list\&. (Without +LATERAL, each sub\-\fBSELECT\fR +is evaluated independently and so cannot cross\-reference any other +FROM +item\&.) +.sp +LATERAL +can also precede a function\-call +FROM +item, but in this case it is a noise word, because the function expression can refer to earlier +FROM +items in any case\&. +.sp +A +LATERAL +item can appear at top level in the +FROM +list, or within a +JOIN +tree\&. In the latter case it can also refer to any items that are on the left\-hand side of a +JOIN +that it is on the right\-hand side of\&. +.sp +When a +FROM +item contains +LATERAL +cross\-references, evaluation proceeds as follows: for each row of the +FROM +item providing the cross\-referenced column(s), or set of rows of multiple +FROM +items providing the columns, the +LATERAL +item is evaluated using that row or row set\*(Aqs values of the columns\&. The resulting row(s) are joined as usual with the rows they were computed from\&. This is repeated for each row or set of rows from the column source table(s)\&. +.sp +The column source table(s) must be +INNER +or +LEFT +joined to the +LATERAL +item, else there would not be a well\-defined set of rows from which to compute each set of rows for the +LATERAL +item\&. Thus, although a construct such as +\fIX\fR RIGHT JOIN LATERAL \fIY\fR +is syntactically valid, it is not actually allowed for +\fIY\fR +to reference +\fIX\fR\&. +.RE +.SS "WHERE Clause" +.PP +The optional +WHERE +clause has the general form +.sp +.if n \{\ +.RS 4 +.\} +.nf +WHERE \fIcondition\fR +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIcondition\fR +is any expression that evaluates to a result of type +boolean\&. Any row that does not satisfy this condition will be eliminated from the output\&. A row satisfies the condition if it returns true when the actual row values are substituted for any variable references\&. +.SS "GROUP BY Clause" +.PP +The optional +GROUP BY +clause has the general form +.sp +.if n \{\ +.RS 4 +.\} +.nf +GROUP BY [ ALL | DISTINCT ] \fIgrouping_element\fR [, \&.\&.\&.] +.fi +.if n \{\ +.RE +.\} +.PP +GROUP BY +will condense into a single row all selected rows that share the same values for the grouped expressions\&. An +\fIexpression\fR +used inside a +\fIgrouping_element\fR +can be an input column name, or the name or ordinal number of an output column (\fBSELECT\fR +list item), or an arbitrary expression formed from input\-column values\&. In case of ambiguity, a +GROUP BY +name will be interpreted as an input\-column name rather than an output column name\&. +.PP +If any of +GROUPING SETS, +ROLLUP +or +CUBE +are present as grouping elements, then the +GROUP BY +clause as a whole defines some number of independent +\fIgrouping sets\fR\&. The effect of this is equivalent to constructing a +UNION ALL +between subqueries with the individual grouping sets as their +GROUP BY +clauses\&. The optional +DISTINCT +clause removes duplicate sets before processing; it does +\fInot\fR +transform the +UNION ALL +into a +UNION DISTINCT\&. For further details on the handling of grouping sets see +Section\ \&7.2.4\&. +.PP +Aggregate functions, if any are used, are computed across all rows making up each group, producing a separate value for each group\&. (If there are aggregate functions but no +GROUP BY +clause, the query is treated as having a single group comprising all the selected rows\&.) The set of rows fed to each aggregate function can be further filtered by attaching a +FILTER +clause to the aggregate function call; see +Section\ \&4.2.7 +for more information\&. When a +FILTER +clause is present, only those rows matching it are included in the input to that aggregate function\&. +.PP +When +GROUP BY +is present, or any aggregate functions are present, it is not valid for the +\fBSELECT\fR +list expressions to refer to ungrouped columns except within aggregate functions or when the ungrouped column is functionally dependent on the grouped columns, since there would otherwise be more than one possible value to return for an ungrouped column\&. A functional dependency exists if the grouped columns (or a subset thereof) are the primary key of the table containing the ungrouped column\&. +.PP +Keep in mind that all aggregate functions are evaluated before evaluating any +\(lqscalar\(rq +expressions in the +HAVING +clause or +SELECT +list\&. This means that, for example, a +CASE +expression cannot be used to skip evaluation of an aggregate function; see +Section\ \&4.2.14\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified with +GROUP BY\&. +.SS "HAVING Clause" +.PP +The optional +HAVING +clause has the general form +.sp +.if n \{\ +.RS 4 +.\} +.nf +HAVING \fIcondition\fR +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIcondition\fR +is the same as specified for the +WHERE +clause\&. +.PP +HAVING +eliminates group rows that do not satisfy the condition\&. +HAVING +is different from +WHERE: +WHERE +filters individual rows before the application of +GROUP BY, while +HAVING +filters group rows created by +GROUP BY\&. Each column referenced in +\fIcondition\fR +must unambiguously reference a grouping column, unless the reference appears within an aggregate function or the ungrouped column is functionally dependent on the grouping columns\&. +.PP +The presence of +HAVING +turns a query into a grouped query even if there is no +GROUP BY +clause\&. This is the same as what happens when the query contains aggregate functions but no +GROUP BY +clause\&. All the selected rows are considered to form a single group, and the +\fBSELECT\fR +list and +HAVING +clause can only reference table columns from within aggregate functions\&. Such a query will emit a single row if the +HAVING +condition is true, zero rows if it is not true\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified with +HAVING\&. +.SS "WINDOW Clause" +.PP +The optional +WINDOW +clause has the general form +.sp +.if n \{\ +.RS 4 +.\} +.nf +WINDOW \fIwindow_name\fR AS ( \fIwindow_definition\fR ) [, \&.\&.\&.] +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIwindow_name\fR +is a name that can be referenced from +OVER +clauses or subsequent window definitions, and +\fIwindow_definition\fR +is +.sp +.if n \{\ +.RS 4 +.\} +.nf +[ \fIexisting_window_name\fR ] +[ PARTITION BY \fIexpression\fR [, \&.\&.\&.] ] +[ ORDER BY \fIexpression\fR [ ASC | DESC | USING \fIoperator\fR ] [ NULLS { FIRST | LAST } ] [, \&.\&.\&.] ] +[ \fIframe_clause\fR ] +.fi +.if n \{\ +.RE +.\} +.PP +If an +\fIexisting_window_name\fR +is specified it must refer to an earlier entry in the +WINDOW +list; the new window copies its partitioning clause from that entry, as well as its ordering clause if any\&. In this case the new window cannot specify its own +PARTITION BY +clause, and it can specify +ORDER BY +only if the copied window does not have one\&. The new window always uses its own frame clause; the copied window must not specify a frame clause\&. +.PP +The elements of the +PARTITION BY +list are interpreted in much the same fashion as elements of a +GROUP BY +clause, except that they are always simple expressions and never the name or number of an output column\&. Another difference is that these expressions can contain aggregate function calls, which are not allowed in a regular +GROUP BY +clause\&. They are allowed here because windowing occurs after grouping and aggregation\&. +.PP +Similarly, the elements of the +ORDER BY +list are interpreted in much the same fashion as elements of a statement\-level +ORDER BY +clause, except that the expressions are always taken as simple expressions and never the name or number of an output column\&. +.PP +The optional +\fIframe_clause\fR +defines the +window frame +for window functions that depend on the frame (not all do)\&. The window frame is a set of related rows for each row of the query (called the +current row)\&. The +\fIframe_clause\fR +can be one of +.sp +.if n \{\ +.RS 4 +.\} +.nf +{ RANGE | ROWS | GROUPS } \fIframe_start\fR [ \fIframe_exclusion\fR ] +{ RANGE | ROWS | GROUPS } BETWEEN \fIframe_start\fR AND \fIframe_end\fR [ \fIframe_exclusion\fR ] +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIframe_start\fR +and +\fIframe_end\fR +can be one of +.sp +.if n \{\ +.RS 4 +.\} +.nf +UNBOUNDED PRECEDING +\fIoffset\fR PRECEDING +CURRENT ROW +\fIoffset\fR FOLLOWING +UNBOUNDED FOLLOWING +.fi +.if n \{\ +.RE +.\} +.sp +and +\fIframe_exclusion\fR +can be one of +.sp +.if n \{\ +.RS 4 +.\} +.nf +EXCLUDE CURRENT ROW +EXCLUDE GROUP +EXCLUDE TIES +EXCLUDE NO OTHERS +.fi +.if n \{\ +.RE +.\} +.sp +If +\fIframe_end\fR +is omitted it defaults to +CURRENT ROW\&. Restrictions are that +\fIframe_start\fR +cannot be +UNBOUNDED FOLLOWING, +\fIframe_end\fR +cannot be +UNBOUNDED PRECEDING, and the +\fIframe_end\fR +choice cannot appear earlier in the above list of +\fIframe_start\fR +and +\fIframe_end\fR +options than the +\fIframe_start\fR +choice does \(em for example +RANGE BETWEEN CURRENT ROW AND \fIoffset\fR PRECEDING +is not allowed\&. +.PP +The default framing option is +RANGE UNBOUNDED PRECEDING, which is the same as +RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW; it sets the frame to be all rows from the partition start up through the current row\*(Aqs last +peer +(a row that the window\*(Aqs +ORDER BY +clause considers equivalent to the current row; all rows are peers if there is no +ORDER BY)\&. In general, +UNBOUNDED PRECEDING +means that the frame starts with the first row of the partition, and similarly +UNBOUNDED FOLLOWING +means that the frame ends with the last row of the partition, regardless of +RANGE, +ROWS +or +GROUPS +mode\&. In +ROWS +mode, +CURRENT ROW +means that the frame starts or ends with the current row; but in +RANGE +or +GROUPS +mode it means that the frame starts or ends with the current row\*(Aqs first or last peer in the +ORDER BY +ordering\&. The +\fIoffset\fR +PRECEDING +and +\fIoffset\fR +FOLLOWING +options vary in meaning depending on the frame mode\&. In +ROWS +mode, the +\fIoffset\fR +is an integer indicating that the frame starts or ends that many rows before or after the current row\&. In +GROUPS +mode, the +\fIoffset\fR +is an integer indicating that the frame starts or ends that many peer groups before or after the current row\*(Aqs peer group, where a +peer group +is a group of rows that are equivalent according to the window\*(Aqs +ORDER BY +clause\&. In +RANGE +mode, use of an +\fIoffset\fR +option requires that there be exactly one +ORDER BY +column in the window definition\&. Then the frame contains those rows whose ordering column value is no more than +\fIoffset\fR +less than (for +PRECEDING) or more than (for +FOLLOWING) the current row\*(Aqs ordering column value\&. In these cases the data type of the +\fIoffset\fR +expression depends on the data type of the ordering column\&. For numeric ordering columns it is typically of the same type as the ordering column, but for datetime ordering columns it is an +interval\&. In all these cases, the value of the +\fIoffset\fR +must be non\-null and non\-negative\&. Also, while the +\fIoffset\fR +does not have to be a simple constant, it cannot contain variables, aggregate functions, or window functions\&. +.PP +The +\fIframe_exclusion\fR +option allows rows around the current row to be excluded from the frame, even if they would be included according to the frame start and frame end options\&. +EXCLUDE CURRENT ROW +excludes the current row from the frame\&. +EXCLUDE GROUP +excludes the current row and its ordering peers from the frame\&. +EXCLUDE TIES +excludes any peers of the current row from the frame, but not the current row itself\&. +EXCLUDE NO OTHERS +simply specifies explicitly the default behavior of not excluding the current row or its peers\&. +.PP +Beware that the +ROWS +mode can produce unpredictable results if the +ORDER BY +ordering does not order the rows uniquely\&. The +RANGE +and +GROUPS +modes are designed to ensure that rows that are peers in the +ORDER BY +ordering are treated alike: all rows of a given peer group will be in the frame or excluded from it\&. +.PP +The purpose of a +WINDOW +clause is to specify the behavior of +window functions +appearing in the query\*(Aqs +\fBSELECT\fR list +or +ORDER BY +clause\&. These functions can reference the +WINDOW +clause entries by name in their +OVER +clauses\&. A +WINDOW +clause entry does not have to be referenced anywhere, however; if it is not used in the query it is simply ignored\&. It is possible to use window functions without any +WINDOW +clause at all, since a window function call can specify its window definition directly in its +OVER +clause\&. However, the +WINDOW +clause saves typing when the same window definition is needed for more than one window function\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified with +WINDOW\&. +.PP +Window functions are described in detail in +Section\ \&3.5, +Section\ \&4.2.8, and +Section\ \&7.2.5\&. +.SS "SELECT List" +.PP +The +\fBSELECT\fR +list (between the key words +SELECT +and +FROM) specifies expressions that form the output rows of the +\fBSELECT\fR +statement\&. The expressions can (and usually do) refer to columns computed in the +FROM +clause\&. +.PP +Just as in a table, every output column of a +\fBSELECT\fR +has a name\&. In a simple +\fBSELECT\fR +this name is just used to label the column for display, but when the +\fBSELECT\fR +is a sub\-query of a larger query, the name is seen by the larger query as the column name of the virtual table produced by the sub\-query\&. To specify the name to use for an output column, write +AS +\fIoutput_name\fR +after the column\*(Aqs expression\&. (You can omit +AS, but only if the desired output name does not match any +PostgreSQL +keyword (see +Appendix\ \&C)\&. For protection against possible future keyword additions, it is recommended that you always either write +AS +or double\-quote the output name\&.) If you do not specify a column name, a name is chosen automatically by +PostgreSQL\&. If the column\*(Aqs expression is a simple column reference then the chosen name is the same as that column\*(Aqs name\&. In more complex cases a function or type name may be used, or the system may fall back on a generated name such as +?column?\&. +.PP +An output column\*(Aqs name can be used to refer to the column\*(Aqs value in +ORDER BY +and +GROUP BY +clauses, but not in the +WHERE +or +HAVING +clauses; there you must write out the expression instead\&. +.PP +Instead of an expression, +* +can be written in the output list as a shorthand for all the columns of the selected rows\&. Also, you can write +\fItable_name\fR\&.* +as a shorthand for the columns coming from just that table\&. In these cases it is not possible to specify new names with +AS; the output column names will be the same as the table columns\*(Aq names\&. +.PP +According to the SQL standard, the expressions in the output list should be computed before applying +DISTINCT, +ORDER BY, or +LIMIT\&. This is obviously necessary when using +DISTINCT, since otherwise it\*(Aqs not clear what values are being made distinct\&. However, in many cases it is convenient if output expressions are computed after +ORDER BY +and +LIMIT; particularly if the output list contains any volatile or expensive functions\&. With that behavior, the order of function evaluations is more intuitive and there will not be evaluations corresponding to rows that never appear in the output\&. +PostgreSQL +will effectively evaluate output expressions after sorting and limiting, so long as those expressions are not referenced in +DISTINCT, +ORDER BY +or +GROUP BY\&. (As a counterexample, +SELECT f(x) FROM tab ORDER BY 1 +clearly must evaluate +\fBf(x)\fR +before sorting\&.) Output expressions that contain set\-returning functions are effectively evaluated after sorting and before limiting, so that +LIMIT +will act to cut off the output from a set\-returning function\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +PostgreSQL +versions before 9\&.6 did not provide any guarantees about the timing of evaluation of output expressions versus sorting and limiting; it depended on the form of the chosen query plan\&. +.sp .5v +.RE +.SS "DISTINCT Clause" +.PP +If +SELECT DISTINCT +is specified, all duplicate rows are removed from the result set (one row is kept from each group of duplicates)\&. +SELECT ALL +specifies the opposite: all rows are kept; that is the default\&. +.PP +SELECT DISTINCT ON ( \fIexpression\fR [, \&.\&.\&.] ) +keeps only the first row of each set of rows where the given expressions evaluate to equal\&. The +DISTINCT ON +expressions are interpreted using the same rules as for +ORDER BY +(see above)\&. Note that the +\(lqfirst row\(rq +of each set is unpredictable unless +ORDER BY +is used to ensure that the desired row appears first\&. For example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT DISTINCT ON (location) location, time, report + FROM weather_reports + ORDER BY location, time DESC; +.fi +.if n \{\ +.RE +.\} +.sp +retrieves the most recent weather report for each location\&. But if we had not used +ORDER BY +to force descending order of time values for each location, we\*(Aqd have gotten a report from an unpredictable time for each location\&. +.PP +The +DISTINCT ON +expression(s) must match the leftmost +ORDER BY +expression(s)\&. The +ORDER BY +clause will normally contain additional expression(s) that determine the desired precedence of rows within each +DISTINCT ON +group\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified with +DISTINCT\&. +.SS "UNION Clause" +.PP +The +UNION +clause has this general form: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIselect_statement\fR UNION [ ALL | DISTINCT ] \fIselect_statement\fR +.fi +.if n \{\ +.RE +.\} +.sp +\fIselect_statement\fR +is any +\fBSELECT\fR +statement without an +ORDER BY, +LIMIT, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE, or +FOR KEY SHARE +clause\&. (ORDER BY +and +LIMIT +can be attached to a subexpression if it is enclosed in parentheses\&. Without parentheses, these clauses will be taken to apply to the result of the +UNION, not to its right\-hand input expression\&.) +.PP +The +UNION +operator computes the set union of the rows returned by the involved +\fBSELECT\fR +statements\&. A row is in the set union of two result sets if it appears in at least one of the result sets\&. The two +\fBSELECT\fR +statements that represent the direct operands of the +UNION +must produce the same number of columns, and corresponding columns must be of compatible data types\&. +.PP +The result of +UNION +does not contain any duplicate rows unless the +ALL +option is specified\&. +ALL +prevents elimination of duplicates\&. (Therefore, +UNION ALL +is usually significantly quicker than +UNION; use +ALL +when you can\&.) +DISTINCT +can be written to explicitly specify the default behavior of eliminating duplicate rows\&. +.PP +Multiple +UNION +operators in the same +\fBSELECT\fR +statement are evaluated left to right, unless otherwise indicated by parentheses\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified either for a +UNION +result or for any input of a +UNION\&. +.SS "INTERSECT Clause" +.PP +The +INTERSECT +clause has this general form: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIselect_statement\fR INTERSECT [ ALL | DISTINCT ] \fIselect_statement\fR +.fi +.if n \{\ +.RE +.\} +.sp +\fIselect_statement\fR +is any +\fBSELECT\fR +statement without an +ORDER BY, +LIMIT, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE, or +FOR KEY SHARE +clause\&. +.PP +The +INTERSECT +operator computes the set intersection of the rows returned by the involved +\fBSELECT\fR +statements\&. A row is in the intersection of two result sets if it appears in both result sets\&. +.PP +The result of +INTERSECT +does not contain any duplicate rows unless the +ALL +option is specified\&. With +ALL, a row that has +\fIm\fR +duplicates in the left table and +\fIn\fR +duplicates in the right table will appear min(\fIm\fR,\fIn\fR) times in the result set\&. +DISTINCT +can be written to explicitly specify the default behavior of eliminating duplicate rows\&. +.PP +Multiple +INTERSECT +operators in the same +\fBSELECT\fR +statement are evaluated left to right, unless parentheses dictate otherwise\&. +INTERSECT +binds more tightly than +UNION\&. That is, +A UNION B INTERSECT C +will be read as +A UNION (B INTERSECT C)\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified either for an +INTERSECT +result or for any input of an +INTERSECT\&. +.SS "EXCEPT Clause" +.PP +The +EXCEPT +clause has this general form: +.sp +.if n \{\ +.RS 4 +.\} +.nf +\fIselect_statement\fR EXCEPT [ ALL | DISTINCT ] \fIselect_statement\fR +.fi +.if n \{\ +.RE +.\} +.sp +\fIselect_statement\fR +is any +\fBSELECT\fR +statement without an +ORDER BY, +LIMIT, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE, or +FOR KEY SHARE +clause\&. +.PP +The +EXCEPT +operator computes the set of rows that are in the result of the left +\fBSELECT\fR +statement but not in the result of the right one\&. +.PP +The result of +EXCEPT +does not contain any duplicate rows unless the +ALL +option is specified\&. With +ALL, a row that has +\fIm\fR +duplicates in the left table and +\fIn\fR +duplicates in the right table will appear max(\fIm\fR\-\fIn\fR,0) times in the result set\&. +DISTINCT +can be written to explicitly specify the default behavior of eliminating duplicate rows\&. +.PP +Multiple +EXCEPT +operators in the same +\fBSELECT\fR +statement are evaluated left to right, unless parentheses dictate otherwise\&. +EXCEPT +binds at the same level as +UNION\&. +.PP +Currently, +FOR NO KEY UPDATE, +FOR UPDATE, +FOR SHARE +and +FOR KEY SHARE +cannot be specified either for an +EXCEPT +result or for any input of an +EXCEPT\&. +.SS "ORDER BY Clause" +.PP +The optional +ORDER BY +clause has this general form: +.sp +.if n \{\ +.RS 4 +.\} +.nf +ORDER BY \fIexpression\fR [ ASC | DESC | USING \fIoperator\fR ] [ NULLS { FIRST | LAST } ] [, \&.\&.\&.] +.fi +.if n \{\ +.RE +.\} +.sp +The +ORDER BY +clause causes the result rows to be sorted according to the specified expression(s)\&. If two rows are equal according to the leftmost expression, they are compared according to the next expression and so on\&. If they are equal according to all specified expressions, they are returned in an implementation\-dependent order\&. +.PP +Each +\fIexpression\fR +can be the name or ordinal number of an output column (\fBSELECT\fR +list item), or it can be an arbitrary expression formed from input\-column values\&. +.PP +The ordinal number refers to the ordinal (left\-to\-right) position of the output column\&. This feature makes it possible to define an ordering on the basis of a column that does not have a unique name\&. This is never absolutely necessary because it is always possible to assign a name to an output column using the +AS +clause\&. +.PP +It is also possible to use arbitrary expressions in the +ORDER BY +clause, including columns that do not appear in the +\fBSELECT\fR +output list\&. Thus the following statement is valid: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT name FROM distributors ORDER BY code; +.fi +.if n \{\ +.RE +.\} +.sp +A limitation of this feature is that an +ORDER BY +clause applying to the result of a +UNION, +INTERSECT, or +EXCEPT +clause can only specify an output column name or number, not an expression\&. +.PP +If an +ORDER BY +expression is a simple name that matches both an output column name and an input column name, +ORDER BY +will interpret it as the output column name\&. This is the opposite of the choice that +GROUP BY +will make in the same situation\&. This inconsistency is made to be compatible with the SQL standard\&. +.PP +Optionally one can add the key word +ASC +(ascending) or +DESC +(descending) after any expression in the +ORDER BY +clause\&. If not specified, +ASC +is assumed by default\&. Alternatively, a specific ordering operator name can be specified in the +USING +clause\&. An ordering operator must be a less\-than or greater\-than member of some B\-tree operator family\&. +ASC +is usually equivalent to +USING < +and +DESC +is usually equivalent to +USING >\&. (But the creator of a user\-defined data type can define exactly what the default sort ordering is, and it might correspond to operators with other names\&.) +.PP +If +NULLS LAST +is specified, null values sort after all non\-null values; if +NULLS FIRST +is specified, null values sort before all non\-null values\&. If neither is specified, the default behavior is +NULLS LAST +when +ASC +is specified or implied, and +NULLS FIRST +when +DESC +is specified (thus, the default is to act as though nulls are larger than non\-nulls)\&. When +USING +is specified, the default nulls ordering depends on whether the operator is a less\-than or greater\-than operator\&. +.PP +Note that ordering options apply only to the expression they follow; for example +ORDER BY x, y DESC +does not mean the same thing as +ORDER BY x DESC, y DESC\&. +.PP +Character\-string data is sorted according to the collation that applies to the column being sorted\&. That can be overridden at need by including a +COLLATE +clause in the +\fIexpression\fR, for example +ORDER BY mycolumn COLLATE "en_US"\&. For more information see +Section\ \&4.2.10 +and +Section\ \&24.2\&. +.SS "LIMIT Clause" +.PP +The +LIMIT +clause consists of two independent sub\-clauses: +.sp +.if n \{\ +.RS 4 +.\} +.nf +LIMIT { \fIcount\fR | ALL } +OFFSET \fIstart\fR +.fi +.if n \{\ +.RE +.\} +.sp +The parameter +\fIcount\fR +specifies the maximum number of rows to return, while +\fIstart\fR +specifies the number of rows to skip before starting to return rows\&. When both are specified, +\fIstart\fR +rows are skipped before starting to count the +\fIcount\fR +rows to be returned\&. +.PP +If the +\fIcount\fR +expression evaluates to NULL, it is treated as +LIMIT ALL, i\&.e\&., no limit\&. If +\fIstart\fR +evaluates to NULL, it is treated the same as +OFFSET 0\&. +.PP +SQL:2008 introduced a different syntax to achieve the same result, which +PostgreSQL +also supports\&. It is: +.sp +.if n \{\ +.RS 4 +.\} +.nf +OFFSET \fIstart\fR { ROW | ROWS } +FETCH { FIRST | NEXT } [ \fIcount\fR ] { ROW | ROWS } { ONLY | WITH TIES } +.fi +.if n \{\ +.RE +.\} +.sp +In this syntax, the +\fIstart\fR +or +\fIcount\fR +value is required by the standard to be a literal constant, a parameter, or a variable name; as a +PostgreSQL +extension, other expressions are allowed, but will generally need to be enclosed in parentheses to avoid ambiguity\&. If +\fIcount\fR +is omitted in a +FETCH +clause, it defaults to 1\&. The +WITH TIES +option is used to return any additional rows that tie for the last place in the result set according to the +ORDER BY +clause; +ORDER BY +is mandatory in this case, and +SKIP LOCKED +is not allowed\&. +ROW +and +ROWS +as well as +FIRST +and +NEXT +are noise words that don\*(Aqt influence the effects of these clauses\&. According to the standard, the +OFFSET +clause must come before the +FETCH +clause if both are present; but +PostgreSQL +is laxer and allows either order\&. +.PP +When using +LIMIT, it is a good idea to use an +ORDER BY +clause that constrains the result rows into a unique order\&. Otherwise you will get an unpredictable subset of the query\*(Aqs rows \(em you might be asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? You don\*(Aqt know what ordering unless you specify +ORDER BY\&. +.PP +The query planner takes +LIMIT +into account when generating a query plan, so you are very likely to get different plans (yielding different row orders) depending on what you use for +LIMIT +and +OFFSET\&. Thus, using different +LIMIT/OFFSET +values to select different subsets of a query result +\fIwill give inconsistent results\fR +unless you enforce a predictable result ordering with +ORDER BY\&. This is not a bug; it is an inherent consequence of the fact that SQL does not promise to deliver the results of a query in any particular order unless +ORDER BY +is used to constrain the order\&. +.PP +It is even possible for repeated executions of the same +LIMIT +query to return different subsets of the rows of a table, if there is not an +ORDER BY +to enforce selection of a deterministic subset\&. Again, this is not a bug; determinism of the results is simply not guaranteed in such a case\&. +.SS "The Locking Clause" +.PP +FOR UPDATE, +FOR NO KEY UPDATE, +FOR SHARE +and +FOR KEY SHARE +are +locking clauses; they affect how +SELECT +locks rows as they are obtained from the table\&. +.PP +The locking clause has the general form +.sp +.if n \{\ +.RS 4 +.\} +.nf +FOR \fIlock_strength\fR [ OF \fItable_name\fR [, \&.\&.\&.] ] [ NOWAIT | SKIP LOCKED ] +.fi +.if n \{\ +.RE +.\} +.sp +where +\fIlock_strength\fR +can be one of +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE +NO KEY UPDATE +SHARE +KEY SHARE +.fi +.if n \{\ +.RE +.\} +.PP +For more information on each row\-level lock mode, refer to +Section\ \&13.3.2\&. +.PP +To prevent the operation from waiting for other transactions to commit, use either the +NOWAIT +or +SKIP LOCKED +option\&. With +NOWAIT, the statement reports an error, rather than waiting, if a selected row cannot be locked immediately\&. With +SKIP LOCKED, any selected rows that cannot be immediately locked are skipped\&. Skipping locked rows provides an inconsistent view of the data, so this is not suitable for general purpose work, but can be used to avoid lock contention with multiple consumers accessing a queue\-like table\&. Note that +NOWAIT +and +SKIP LOCKED +apply only to the row\-level lock(s) \(em the required +ROW SHARE +table\-level lock is still taken in the ordinary way (see +Chapter\ \&13)\&. You can use +\fBLOCK\fR +with the +NOWAIT +option first, if you need to acquire the table\-level lock without waiting\&. +.PP +If specific tables are named in a locking clause, then only rows coming from those tables are locked; any other tables used in the +\fBSELECT\fR +are simply read as usual\&. A locking clause without a table list affects all tables used in the statement\&. If a locking clause is applied to a view or sub\-query, it affects all tables used in the view or sub\-query\&. However, these clauses do not apply to +WITH +queries referenced by the primary query\&. If you want row locking to occur within a +WITH +query, specify a locking clause within the +WITH +query\&. +.PP +Multiple locking clauses can be written if it is necessary to specify different locking behavior for different tables\&. If the same table is mentioned (or implicitly affected) by more than one locking clause, then it is processed as if it was only specified by the strongest one\&. Similarly, a table is processed as +NOWAIT +if that is specified in any of the clauses affecting it\&. Otherwise, it is processed as +SKIP LOCKED +if that is specified in any of the clauses affecting it\&. +.PP +The locking clauses cannot be used in contexts where returned rows cannot be clearly identified with individual table rows; for example they cannot be used with aggregation\&. +.PP +When a locking clause appears at the top level of a +\fBSELECT\fR +query, the rows that are locked are exactly those that are returned by the query; in the case of a join query, the rows locked are those that contribute to returned join rows\&. In addition, rows that satisfied the query conditions as of the query snapshot will be locked, although they will not be returned if they were updated after the snapshot and no longer satisfy the query conditions\&. If a +LIMIT +is used, locking stops once enough rows have been returned to satisfy the limit (but note that rows skipped over by +OFFSET +will get locked)\&. Similarly, if a locking clause is used in a cursor\*(Aqs query, only rows actually fetched or stepped past by the cursor will be locked\&. +.PP +When a locking clause appears in a sub\-\fBSELECT\fR, the rows locked are those returned to the outer query by the sub\-query\&. This might involve fewer rows than inspection of the sub\-query alone would suggest, since conditions from the outer query might be used to optimize execution of the sub\-query\&. For example, +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss WHERE col1 = 5; +.fi +.if n \{\ +.RE +.\} +.sp +will lock only rows having +col1 = 5, even though that condition is not textually within the sub\-query\&. +.PP +Previous releases failed to preserve a lock which is upgraded by a later savepoint\&. For example, this code: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; +SELECT * FROM mytable WHERE key = 1 FOR UPDATE; +SAVEPOINT s; +UPDATE mytable SET \&.\&.\&. WHERE key = 1; +ROLLBACK TO s; +.fi +.if n \{\ +.RE +.\} +.sp +would fail to preserve the +FOR UPDATE +lock after the +\fBROLLBACK TO\fR\&. This has been fixed in release 9\&.3\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBCaution\fR +.ps -1 +.br +.PP +It is possible for a +\fBSELECT\fR +command running at the +READ COMMITTED +transaction isolation level and using +ORDER BY +and a locking clause to return rows out of order\&. This is because +ORDER BY +is applied first\&. The command sorts the result, but might then block trying to obtain a lock on one or more of the rows\&. Once the +SELECT +unblocks, some of the ordering column values might have been modified, leading to those rows appearing to be out of order (though they are in order in terms of the original column values)\&. This can be worked around at need by placing the +FOR UPDATE/SHARE +clause in a sub\-query, for example +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss ORDER BY column1; +.fi +.if n \{\ +.RE +.\} +.sp +Note that this will result in locking all rows of +mytable, whereas +FOR UPDATE +at the top level would lock only the actually returned rows\&. This can make for a significant performance difference, particularly if the +ORDER BY +is combined with +LIMIT +or other restrictions\&. So this technique is recommended only if concurrent updates of the ordering columns are expected and a strictly sorted result is required\&. +.PP +At the +REPEATABLE READ +or +SERIALIZABLE +transaction isolation level this would cause a serialization failure (with an +SQLSTATE +of +\*(Aq40001\*(Aq), so there is no possibility of receiving rows out of order under these isolation levels\&. +.sp .5v +.RE +.SS "TABLE Command" +.PP +The command +.sp +.if n \{\ +.RS 4 +.\} +.nf +TABLE \fIname\fR +.fi +.if n \{\ +.RE +.\} +.sp +is equivalent to +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM \fIname\fR +.fi +.if n \{\ +.RE +.\} +.sp +It can be used as a top\-level command or as a space\-saving syntax variant in parts of complex queries\&. Only the +WITH, +UNION, +INTERSECT, +EXCEPT, +ORDER BY, +LIMIT, +OFFSET, +FETCH +and +FOR +locking clauses can be used with +\fBTABLE\fR; the +WHERE +clause and any form of aggregation cannot be used\&. +.SH "EXAMPLES" +.PP +To join the table +films +with the table +distributors: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT f\&.title, f\&.did, d\&.name, f\&.date_prod, f\&.kind + FROM distributors d JOIN films f USING (did); + + title | did | name | date_prod | kind +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\- + The Third Man | 101 | British Lion | 1949\-12\-23 | Drama + The African Queen | 101 | British Lion | 1951\-08\-11 | Romantic + \&.\&.\&. +.fi +.if n \{\ +.RE +.\} +.PP +To sum the column +len +of all films and group the results by +kind: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT kind, sum(len) AS total FROM films GROUP BY kind; + + kind | total +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- + Action | 07:34 + Comedy | 02:58 + Drama | 14:28 + Musical | 06:42 + Romantic | 04:38 +.fi +.if n \{\ +.RE +.\} +.PP +To sum the column +len +of all films, group the results by +kind +and show those group totals that are less than 5 hours: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT kind, sum(len) AS total + FROM films + GROUP BY kind + HAVING sum(len) < interval \*(Aq5 hours\*(Aq; + + kind | total +\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\- + Comedy | 02:58 + Romantic | 04:38 +.fi +.if n \{\ +.RE +.\} +.PP +The following two examples are identical ways of sorting the individual results according to the contents of the second column (name): +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM distributors ORDER BY name; +SELECT * FROM distributors ORDER BY 2; + + did | name +\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 109 | 20th Century Fox + 110 | Bavaria Atelier + 101 | British Lion + 107 | Columbia + 102 | Jean Luc Godard + 113 | Luso films + 104 | Mosfilm + 103 | Paramount + 106 | Toho + 105 | United Artists + 111 | Walt Disney + 112 | Warner Bros\&. + 108 | Westward +.fi +.if n \{\ +.RE +.\} +.PP +The next example shows how to obtain the union of the tables +distributors +and +actors, restricting the results to those that begin with the letter W in each table\&. Only distinct rows are wanted, so the key word +ALL +is omitted\&. +.sp +.if n \{\ +.RS 4 +.\} +.nf +distributors: actors: + did | name id | name +\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 108 | Westward 1 | Woody Allen + 111 | Walt Disney 2 | Warren Beatty + 112 | Warner Bros\&. 3 | Walter Matthau + \&.\&.\&. \&.\&.\&. + +SELECT distributors\&.name + FROM distributors + WHERE distributors\&.name LIKE \*(AqW%\*(Aq +UNION +SELECT actors\&.name + FROM actors + WHERE actors\&.name LIKE \*(AqW%\*(Aq; + + name +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + Walt Disney + Walter Matthau + Warner Bros\&. + Warren Beatty + Westward + Woody Allen +.fi +.if n \{\ +.RE +.\} +.PP +This example shows how to use a function in the +FROM +clause, both with and without a column definition list: +.sp +.if n \{\ +.RS 4 +.\} +.nf +CREATE FUNCTION distributors(int) RETURNS SETOF distributors AS $$ + SELECT * FROM distributors WHERE did = $1; +$$ LANGUAGE SQL; + +SELECT * FROM distributors(111); + did | name +\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\- + 111 | Walt Disney + +CREATE FUNCTION distributors_2(int) RETURNS SETOF record AS $$ + SELECT * FROM distributors WHERE did = $1; +$$ LANGUAGE SQL; + +SELECT * FROM distributors_2(111) AS (f1 int, f2 text); + f1 | f2 +\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\- + 111 | Walt Disney +.fi +.if n \{\ +.RE +.\} +.PP +Here is an example of a function with an ordinality column added: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM unnest(ARRAY[\*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq,\*(Aqd\*(Aq,\*(Aqe\*(Aq,\*(Aqf\*(Aq]) WITH ORDINALITY; + unnest | ordinality +\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\- + a | 1 + b | 2 + c | 3 + d | 4 + e | 5 + f | 6 +(6 rows) +.fi +.if n \{\ +.RE +.\} +.PP +This example shows how to use a simple +WITH +clause: +.sp +.if n \{\ +.RS 4 +.\} +.nf +WITH t AS ( + SELECT random() as x FROM generate_series(1, 3) + ) +SELECT * FROM t +UNION ALL +SELECT * FROM t + + x +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 0\&.534150459803641 + 0\&.520092216785997 + 0\&.0735620250925422 + 0\&.534150459803641 + 0\&.520092216785997 + 0\&.0735620250925422 +.fi +.if n \{\ +.RE +.\} +.sp +Notice that the +WITH +query was evaluated only once, so that we got two sets of the same three random values\&. +.PP +This example uses +WITH RECURSIVE +to find all subordinates (direct or indirect) of the employee Mary, and their level of indirectness, from a table that shows only direct subordinates: +.sp +.if n \{\ +.RS 4 +.\} +.nf +WITH RECURSIVE employee_recursive(distance, employee_name, manager_name) AS ( + SELECT 1, employee_name, manager_name + FROM employee + WHERE manager_name = \*(AqMary\*(Aq + UNION ALL + SELECT er\&.distance + 1, e\&.employee_name, e\&.manager_name + FROM employee_recursive er, employee e + WHERE er\&.employee_name = e\&.manager_name + ) +SELECT distance, employee_name FROM employee_recursive; +.fi +.if n \{\ +.RE +.\} +.sp +Notice the typical form of recursive queries: an initial condition, followed by +UNION, followed by the recursive part of the query\&. Be sure that the recursive part of the query will eventually return no tuples, or else the query will loop indefinitely\&. (See +Section\ \&7.8 +for more examples\&.) +.PP +This example uses +LATERAL +to apply a set\-returning function +\fBget_product_names()\fR +for each row of the +manufacturers +table: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT m\&.name AS mname, pname +FROM manufacturers m, LATERAL get_product_names(m\&.id) pname; +.fi +.if n \{\ +.RE +.\} +.sp +Manufacturers not currently having any products would not appear in the result, since it is an inner join\&. If we wished to include the names of such manufacturers in the result, we could do: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT m\&.name AS mname, pname +FROM manufacturers m LEFT JOIN LATERAL get_product_names(m\&.id) pname ON true; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +Of course, the +\fBSELECT\fR +statement is compatible with the SQL standard\&. But there are some extensions and some missing features\&. +.SS "Omitted FROM Clauses" +.PP +PostgreSQL +allows one to omit the +FROM +clause\&. It has a straightforward use to compute the results of simple expressions: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT 2+2; + + ?column? +\-\-\-\-\-\-\-\-\-\- + 4 +.fi +.if n \{\ +.RE +.\} +.sp +Some other +SQL +databases cannot do this except by introducing a dummy one\-row table from which to do the +\fBSELECT\fR\&. +.SS "Empty SELECT Lists" +.PP +The list of output expressions after +SELECT +can be empty, producing a zero\-column result table\&. This is not valid syntax according to the SQL standard\&. +PostgreSQL +allows it to be consistent with allowing zero\-column tables\&. However, an empty list is not allowed when +DISTINCT +is used\&. +.SS "Omitting the AS Key Word" +.PP +In the SQL standard, the optional key word +AS +can be omitted before an output column name whenever the new column name is a valid column name (that is, not the same as any reserved keyword)\&. +PostgreSQL +is slightly more restrictive: +AS +is required if the new column name matches any keyword at all, reserved or not\&. Recommended practice is to use +AS +or double\-quote output column names, to prevent any possible conflict against future keyword additions\&. +.PP +In +FROM +items, both the standard and +PostgreSQL +allow +AS +to be omitted before an alias that is an unreserved keyword\&. But this is impractical for output column names, because of syntactic ambiguities\&. +.SS "ONLY and Inheritance" +.PP +The SQL standard requires parentheses around the table name when writing +ONLY, for example +SELECT * FROM ONLY (tab1), ONLY (tab2) WHERE \&.\&.\&.\&. +PostgreSQL +considers these parentheses to be optional\&. +.PP +PostgreSQL +allows a trailing +* +to be written to explicitly specify the non\-ONLY +behavior of including child tables\&. The standard does not allow this\&. +.PP +(These points apply equally to all SQL commands supporting the +ONLY +option\&.) +.SS "TABLESAMPLE Clause Restrictions" +.PP +The +TABLESAMPLE +clause is currently accepted only on regular tables and materialized views\&. According to the SQL standard it should be possible to apply it to any +FROM +item\&. +.SS "Function Calls in FROM" +.PP +PostgreSQL +allows a function call to be written directly as a member of the +FROM +list\&. In the SQL standard it would be necessary to wrap such a function call in a sub\-\fBSELECT\fR; that is, the syntax +FROM \fIfunc\fR(\&.\&.\&.) \fIalias\fR +is approximately equivalent to +FROM LATERAL (SELECT \fIfunc\fR(\&.\&.\&.)) \fIalias\fR\&. Note that +LATERAL +is considered to be implicit; this is because the standard requires +LATERAL +semantics for an +UNNEST() +item in +FROM\&. +PostgreSQL +treats +UNNEST() +the same as other set\-returning functions\&. +.SS "Namespace Available to GROUP BY and ORDER BY" +.PP +In the SQL\-92 standard, an +ORDER BY +clause can only use output column names or numbers, while a +GROUP BY +clause can only use expressions based on input column names\&. +PostgreSQL +extends each of these clauses to allow the other choice as well (but it uses the standard\*(Aqs interpretation if there is ambiguity)\&. +PostgreSQL +also allows both clauses to specify arbitrary expressions\&. Note that names appearing in an expression will always be taken as input\-column names, not as output\-column names\&. +.PP +SQL:1999 and later use a slightly different definition which is not entirely upward compatible with SQL\-92\&. In most cases, however, +PostgreSQL +will interpret an +ORDER BY +or +GROUP BY +expression the same way SQL:1999 does\&. +.SS "Functional Dependencies" +.PP +PostgreSQL +recognizes functional dependency (allowing columns to be omitted from +GROUP BY) only when a table\*(Aqs primary key is included in the +GROUP BY +list\&. The SQL standard specifies additional conditions that should be recognized\&. +.SS "LIMIT and OFFSET" +.PP +The clauses +LIMIT +and +OFFSET +are +PostgreSQL\-specific syntax, also used by +MySQL\&. The SQL:2008 standard has introduced the clauses +OFFSET \&.\&.\&. FETCH {FIRST|NEXT} \&.\&.\&. +for the same functionality, as shown above in +LIMIT Clause\&. This syntax is also used by +IBM DB2\&. (Applications written for +Oracle +frequently use a workaround involving the automatically generated +rownum +column, which is not available in PostgreSQL, to implement the effects of these clauses\&.) +.SS "FOR NO KEY UPDATE, FOR UPDATE, FOR SHARE, FOR KEY SHARE" +.PP +Although +FOR UPDATE +appears in the SQL standard, the standard allows it only as an option of +\fBDECLARE CURSOR\fR\&. +PostgreSQL +allows it in any +\fBSELECT\fR +query as well as in sub\-\fBSELECT\fRs, but this is an extension\&. The +FOR NO KEY UPDATE, +FOR SHARE +and +FOR KEY SHARE +variants, as well as the +NOWAIT +and +SKIP LOCKED +options, do not appear in the standard\&. +.SS "Data\-Modifying Statements in WITH" +.PP +PostgreSQL +allows +\fBINSERT\fR, +\fBUPDATE\fR, and +\fBDELETE\fR +to be used as +WITH +queries\&. This is not found in the SQL standard\&. +.SS "Nonstandard Clauses" +.PP +DISTINCT ON ( \&.\&.\&. ) +is an extension of the SQL standard\&. +.PP +ROWS FROM( \&.\&.\&. ) +is an extension of the SQL standard\&. +.PP +The +MATERIALIZED +and +NOT MATERIALIZED +options of +WITH +are extensions of the SQL standard\&. diff --git a/doc/src/sgml/man7/SELECT_INTO.7 b/doc/src/sgml/man7/SELECT_INTO.7 new file mode 100644 index 0000000..217ae85 --- /dev/null +++ b/doc/src/sgml/man7/SELECT_INTO.7 @@ -0,0 +1,147 @@ +'\" t +.\" Title: SELECT INTO +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SELECT INTO" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SELECT_INTO \- define a new table from the results of a query +.SH "SYNOPSIS" +.sp +.nf +[ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ] +SELECT [ ALL | DISTINCT [ ON ( \fIexpression\fR [, \&.\&.\&.] ) ] ] + * | \fIexpression\fR [ [ AS ] \fIoutput_name\fR ] [, \&.\&.\&.] + INTO [ TEMPORARY | TEMP | UNLOGGED ] [ TABLE ] \fInew_table\fR + [ FROM \fIfrom_item\fR [, \&.\&.\&.] ] + [ WHERE \fIcondition\fR ] + [ GROUP BY \fIexpression\fR [, \&.\&.\&.] ] + [ HAVING \fIcondition\fR ] + [ WINDOW \fIwindow_name\fR AS ( \fIwindow_definition\fR ) [, \&.\&.\&.] ] + [ { UNION | INTERSECT | EXCEPT } [ ALL | DISTINCT ] \fIselect\fR ] + [ ORDER BY \fIexpression\fR [ ASC | DESC | USING \fIoperator\fR ] [ NULLS { FIRST | LAST } ] [, \&.\&.\&.] ] + [ LIMIT { \fIcount\fR | ALL } ] + [ OFFSET \fIstart\fR [ ROW | ROWS ] ] + [ FETCH { FIRST | NEXT } [ \fIcount\fR ] { ROW | ROWS } ONLY ] + [ FOR { UPDATE | SHARE } [ OF \fItable_name\fR [, \&.\&.\&.] ] [ NOWAIT ] [\&.\&.\&.] ] +.fi +.SH "DESCRIPTION" +.PP +\fBSELECT INTO\fR +creates a new table and fills it with data computed by a query\&. The data is not returned to the client, as it is with a normal +\fBSELECT\fR\&. The new table\*(Aqs columns have the names and data types associated with the output columns of the +\fBSELECT\fR\&. +.SH "PARAMETERS" +.PP +TEMPORARY or TEMP +.RS 4 +If specified, the table is created as a temporary table\&. Refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for details\&. +.RE +.PP +UNLOGGED +.RS 4 +If specified, the table is created as an unlogged table\&. Refer to +CREATE TABLE (\fBCREATE_TABLE\fR(7)) +for details\&. +.RE +.PP +\fInew_table\fR +.RS 4 +The name (optionally schema\-qualified) of the table to be created\&. +.RE +.PP +All other parameters are described in detail under +\fBSELECT\fR(7)\&. +.SH "NOTES" +.PP +\fBCREATE TABLE AS\fR +is functionally similar to +\fBSELECT INTO\fR\&. +\fBCREATE TABLE AS\fR +is the recommended syntax, since this form of +\fBSELECT INTO\fR +is not available in +ECPG +or +PL/pgSQL, because they interpret the +INTO +clause differently\&. Furthermore, +\fBCREATE TABLE AS\fR +offers a superset of the functionality provided by +\fBSELECT INTO\fR\&. +.PP +In contrast to +\fBCREATE TABLE AS\fR, +\fBSELECT INTO\fR +does not allow specifying properties like a table\*(Aqs access method with +USING \fImethod\fR +or the table\*(Aqs tablespace with +TABLESPACE \fItablespace_name\fR\&. Use +\fBCREATE TABLE AS\fR +if necessary\&. Therefore, the default table access method is chosen for the new table\&. See +default_table_access_method +for more information\&. +.SH "EXAMPLES" +.PP +Create a new table +films_recent +consisting of only recent entries from the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * INTO films_recent FROM films WHERE date_prod >= \*(Aq2002\-01\-01\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The SQL standard uses +\fBSELECT INTO\fR +to represent selecting values into scalar variables of a host program, rather than creating a new table\&. This indeed is the usage found in +ECPG +(see +Chapter\ \&36) and +PL/pgSQL +(see +Chapter\ \&43)\&. The +PostgreSQL +usage of +\fBSELECT INTO\fR +to represent table creation is historical\&. Some other SQL implementations also use +\fBSELECT INTO\fR +in this way (but most SQL implementations support +\fBCREATE TABLE AS\fR +instead)\&. Apart from such compatibility considerations, it is best to use +\fBCREATE TABLE AS\fR +for this purpose in new code\&. +.SH "SEE ALSO" +CREATE TABLE AS (\fBCREATE_TABLE_AS\fR(7)) diff --git a/doc/src/sgml/man7/SET.7 b/doc/src/sgml/man7/SET.7 new file mode 100644 index 0000000..7862c32 --- /dev/null +++ b/doc/src/sgml/man7/SET.7 @@ -0,0 +1,308 @@ +'\" t +.\" Title: SET +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SET" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SET \- change a run\-time parameter +.SH "SYNOPSIS" +.sp +.nf +SET [ SESSION | LOCAL ] \fIconfiguration_parameter\fR { TO | = } { \fIvalue\fR | \*(Aq\fIvalue\fR\*(Aq | DEFAULT } +SET [ SESSION | LOCAL ] TIME ZONE { \fIvalue\fR | \*(Aq\fIvalue\fR\*(Aq | LOCAL | DEFAULT } +.fi +.SH "DESCRIPTION" +.PP +The +\fBSET\fR +command changes run\-time configuration parameters\&. Many of the run\-time parameters listed in +Chapter\ \&20 +can be changed on\-the\-fly with +\fBSET\fR\&. (Some parameters can only be changed by superusers and users who have been granted +SET +privilege on that parameter\&. There are also parameters that cannot be changed after server or session start\&.) +\fBSET\fR +only affects the value used by the current session\&. +.PP +If +\fBSET\fR +(or equivalently +\fBSET SESSION\fR) is issued within a transaction that is later aborted, the effects of the +\fBSET\fR +command disappear when the transaction is rolled back\&. Once the surrounding transaction is committed, the effects will persist until the end of the session, unless overridden by another +\fBSET\fR\&. +.PP +The effects of +\fBSET LOCAL\fR +last only till the end of the current transaction, whether committed or not\&. A special case is +\fBSET\fR +followed by +\fBSET LOCAL\fR +within a single transaction: the +\fBSET LOCAL\fR +value will be seen until the end of the transaction, but afterwards (if the transaction is committed) the +\fBSET\fR +value will take effect\&. +.PP +The effects of +\fBSET\fR +or +\fBSET LOCAL\fR +are also canceled by rolling back to a savepoint that is earlier than the command\&. +.PP +If +\fBSET LOCAL\fR +is used within a function that has a +SET +option for the same variable (see +CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7))), the effects of the +\fBSET LOCAL\fR +command disappear at function exit; that is, the value in effect when the function was called is restored anyway\&. This allows +\fBSET LOCAL\fR +to be used for dynamic or repeated changes of a parameter within a function, while still having the convenience of using the +SET +option to save and restore the caller\*(Aqs value\&. However, a regular +\fBSET\fR +command overrides any surrounding function\*(Aqs +SET +option; its effects will persist unless rolled back\&. +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBNote\fR +.ps -1 +.br +.PP +In +PostgreSQL +versions 8\&.0 through 8\&.2, the effects of a +\fBSET LOCAL\fR +would be canceled by releasing an earlier savepoint, or by successful exit from a +PL/pgSQL +exception block\&. This behavior has been changed because it was deemed unintuitive\&. +.sp .5v +.RE +.SH "PARAMETERS" +.PP +SESSION +.RS 4 +Specifies that the command takes effect for the current session\&. (This is the default if neither +SESSION +nor +LOCAL +appears\&.) +.RE +.PP +LOCAL +.RS 4 +Specifies that the command takes effect for only the current transaction\&. After +\fBCOMMIT\fR +or +\fBROLLBACK\fR, the session\-level setting takes effect again\&. Issuing this outside of a transaction block emits a warning and otherwise has no effect\&. +.RE +.PP +\fIconfiguration_parameter\fR +.RS 4 +Name of a settable run\-time parameter\&. Available parameters are documented in +Chapter\ \&20 +and below\&. +.RE +.PP +\fIvalue\fR +.RS 4 +New value of parameter\&. Values can be specified as string constants, identifiers, numbers, or comma\-separated lists of these, as appropriate for the particular parameter\&. +DEFAULT +can be written to specify resetting the parameter to its default value (that is, whatever value it would have had if no +\fBSET\fR +had been executed in the current session)\&. +.RE +.PP +Besides the configuration parameters documented in +Chapter\ \&20, there are a few that can only be adjusted using the +\fBSET\fR +command or that have a special syntax: +.PP +SCHEMA +.RS 4 +SET SCHEMA \*(Aq\fIvalue\fR\*(Aq +is an alias for +SET search_path TO \fIvalue\fR\&. Only one schema can be specified using this syntax\&. +.RE +.PP +NAMES +.RS 4 +SET NAMES \fIvalue\fR +is an alias for +SET client_encoding TO \fIvalue\fR\&. +.RE +.PP +SEED +.RS 4 +Sets the internal seed for the random number generator (the function +\fBrandom\fR)\&. Allowed values are floating\-point numbers between \-1 and 1 inclusive\&. +.sp +The seed can also be set by invoking the function +\fBsetseed\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT setseed(\fIvalue\fR); +.fi +.if n \{\ +.RE +.\} +.RE +.PP +TIME ZONE +.RS 4 +SET TIME ZONE \*(Aq\fIvalue\fR\*(Aq +is an alias for +SET timezone TO \*(Aq\fIvalue\fR\*(Aq\&. The syntax +SET TIME ZONE +allows special syntax for the time zone specification\&. Here are examples of valid values: +.PP +\*(AqPST8PDT\*(Aq +.RS 4 +The time zone for Berkeley, California\&. +.RE +.PP +\*(AqEurope/Rome\*(Aq +.RS 4 +The time zone for Italy\&. +.RE +.PP +\-7 +.RS 4 +The time zone 7 hours west from UTC (equivalent to PDT)\&. Positive values are east from UTC\&. +.RE +.PP +INTERVAL \*(Aq\-08:00\*(Aq HOUR TO MINUTE +.RS 4 +The time zone 8 hours west from UTC (equivalent to PST)\&. +.RE +.PP +LOCAL +.br +DEFAULT +.RS 4 +Set the time zone to your local time zone (that is, the server\*(Aqs default value of +\fItimezone\fR)\&. +.RE +.sp +Timezone settings given as numbers or intervals are internally translated to POSIX timezone syntax\&. For example, after +SET TIME ZONE \-7, +\fBSHOW TIME ZONE\fR +would report +<\-07>+07\&. +.sp +Time zone abbreviations are not supported by +\fBSET\fR; see +Section\ \&8.5.3 +for more information about time zones\&. +.RE +.SH "NOTES" +.PP +The function +\fBset_config\fR +provides equivalent functionality; see +Section\ \&9.27.1\&. Also, it is possible to UPDATE the +pg_settings +system view to perform the equivalent of +\fBSET\fR\&. +.SH "EXAMPLES" +.PP +Set the schema search path: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SET search_path TO my_schema, public; +.fi +.if n \{\ +.RE +.\} +.PP +Set the style of date to traditional +POSTGRES +with +\(lqday before month\(rq +input convention: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SET datestyle TO postgres, dmy; +.fi +.if n \{\ +.RE +.\} +.PP +Set the time zone for Berkeley, California: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SET TIME ZONE \*(AqPST8PDT\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Set the time zone for Italy: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SET TIME ZONE \*(AqEurope/Rome\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +SET TIME ZONE +extends syntax defined in the SQL standard\&. The standard allows only numeric time zone offsets while +PostgreSQL +allows more flexible time\-zone specifications\&. All other +SET +features are +PostgreSQL +extensions\&. +.SH "SEE ALSO" +\fBRESET\fR(7), \fBSHOW\fR(7) diff --git a/doc/src/sgml/man7/SET_CONSTRAINTS.7 b/doc/src/sgml/man7/SET_CONSTRAINTS.7 new file mode 100644 index 0000000..dc86e2a --- /dev/null +++ b/doc/src/sgml/man7/SET_CONSTRAINTS.7 @@ -0,0 +1,114 @@ +'\" t +.\" Title: SET CONSTRAINTS +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SET CONSTRAINTS" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SET_CONSTRAINTS \- set constraint check timing for the current transaction +.SH "SYNOPSIS" +.sp +.nf +SET CONSTRAINTS { ALL | \fIname\fR [, \&.\&.\&.] } { DEFERRED | IMMEDIATE } +.fi +.SH "DESCRIPTION" +.PP +\fBSET CONSTRAINTS\fR +sets the behavior of constraint checking within the current transaction\&. +IMMEDIATE +constraints are checked at the end of each statement\&. +DEFERRED +constraints are not checked until transaction commit\&. Each constraint has its own +IMMEDIATE +or +DEFERRED +mode\&. +.PP +Upon creation, a constraint is given one of three characteristics: +DEFERRABLE INITIALLY DEFERRED, +DEFERRABLE INITIALLY IMMEDIATE, or +NOT DEFERRABLE\&. The third class is always +IMMEDIATE +and is not affected by the +\fBSET CONSTRAINTS\fR +command\&. The first two classes start every transaction in the indicated mode, but their behavior can be changed within a transaction by +\fBSET CONSTRAINTS\fR\&. +.PP +\fBSET CONSTRAINTS\fR +with a list of constraint names changes the mode of just those constraints (which must all be deferrable)\&. Each constraint name can be schema\-qualified\&. The current schema search path is used to find the first matching name if no schema name is specified\&. +\fBSET CONSTRAINTS ALL\fR +changes the mode of all deferrable constraints\&. +.PP +When +\fBSET CONSTRAINTS\fR +changes the mode of a constraint from +DEFERRED +to +IMMEDIATE, the new mode takes effect retroactively: any outstanding data modifications that would have been checked at the end of the transaction are instead checked during the execution of the +\fBSET CONSTRAINTS\fR +command\&. If any such constraint is violated, the +\fBSET CONSTRAINTS\fR +fails (and does not change the constraint mode)\&. Thus, +\fBSET CONSTRAINTS\fR +can be used to force checking of constraints to occur at a specific point in a transaction\&. +.PP +Currently, only +UNIQUE, +PRIMARY KEY, +REFERENCES +(foreign key), and +EXCLUDE +constraints are affected by this setting\&. +NOT NULL +and +CHECK +constraints are always checked immediately when a row is inserted or modified (\fInot\fR +at the end of the statement)\&. Uniqueness and exclusion constraints that have not been declared +DEFERRABLE +are also checked immediately\&. +.PP +The firing of triggers that are declared as +\(lqconstraint triggers\(rq +is also controlled by this setting \(em they fire at the same time that the associated constraint should be checked\&. +.SH "NOTES" +.PP +Because +PostgreSQL +does not require constraint names to be unique within a schema (but only per\-table), it is possible that there is more than one match for a specified constraint name\&. In this case +\fBSET CONSTRAINTS\fR +will act on all matches\&. For a non\-schema\-qualified name, once a match or matches have been found in some schema in the search path, schemas appearing later in the path are not searched\&. +.PP +This command only alters the behavior of constraints within the current transaction\&. Issuing this outside of a transaction block emits a warning and otherwise has no effect\&. +.SH "COMPATIBILITY" +.PP +This command complies with the behavior defined in the SQL standard, except for the limitation that, in +PostgreSQL, it does not apply to +NOT NULL +and +CHECK +constraints\&. Also, +PostgreSQL +checks non\-deferrable uniqueness constraints immediately, not at end of statement as the standard would suggest\&. diff --git a/doc/src/sgml/man7/SET_ROLE.7 b/doc/src/sgml/man7/SET_ROLE.7 new file mode 100644 index 0000000..2f3f2c6 --- /dev/null +++ b/doc/src/sgml/man7/SET_ROLE.7 @@ -0,0 +1,143 @@ +'\" t +.\" Title: SET ROLE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SET ROLE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SET_ROLE \- set the current user identifier of the current session +.SH "SYNOPSIS" +.sp +.nf +SET [ SESSION | LOCAL ] ROLE \fIrole_name\fR +SET [ SESSION | LOCAL ] ROLE NONE +RESET ROLE +.fi +.SH "DESCRIPTION" +.PP +This command sets the current user identifier of the current SQL session to be +\fIrole_name\fR\&. The role name can be written as either an identifier or a string literal\&. After +\fBSET ROLE\fR, permissions checking for SQL commands is carried out as though the named role were the one that had logged in originally\&. +.PP +The specified +\fIrole_name\fR +must be a role that the current session user is a member of\&. (If the session user is a superuser, any role can be selected\&.) +.PP +The +SESSION +and +LOCAL +modifiers act the same as for the regular +\fBSET\fR +command\&. +.PP +SET ROLE NONE +sets the current user identifier to the current session user identifier, as returned by +\fBsession_user\fR\&. +RESET ROLE +sets the current user identifier to the connection\-time setting specified by the +command\-line options, +\fBALTER ROLE\fR, or +\fBALTER DATABASE\fR, if any such settings exist\&. Otherwise, +RESET ROLE +sets the current user identifier to the current session user identifier\&. These forms can be executed by any user\&. +.SH "NOTES" +.PP +Using this command, it is possible to either add privileges or restrict one\*(Aqs privileges\&. If the session user role has the +INHERIT +attribute, then it automatically has all the privileges of every role that it could +\fBSET ROLE\fR +to; in this case +\fBSET ROLE\fR +effectively drops all the privileges assigned directly to the session user and to the other roles it is a member of, leaving only the privileges available to the named role\&. On the other hand, if the session user role has the +NOINHERIT +attribute, +\fBSET ROLE\fR +drops the privileges assigned directly to the session user and instead acquires the privileges available to the named role\&. +.PP +In particular, when a superuser chooses to +\fBSET ROLE\fR +to a non\-superuser role, they lose their superuser privileges\&. +.PP +\fBSET ROLE\fR +has effects comparable to +\fBSET SESSION AUTHORIZATION\fR, but the privilege checks involved are quite different\&. Also, +\fBSET SESSION AUTHORIZATION\fR +determines which roles are allowable for later +\fBSET ROLE\fR +commands, whereas changing roles with +\fBSET ROLE\fR +does not change the set of roles allowed to a later +\fBSET ROLE\fR\&. +.PP +\fBSET ROLE\fR +does not process session variables as specified by the role\*(Aqs +\fBALTER ROLE\fR +settings; this only happens during login\&. +.PP +\fBSET ROLE\fR +cannot be used within a +SECURITY DEFINER +function\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT SESSION_USER, CURRENT_USER; + + session_user | current_user +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\- + peter | peter + +SET ROLE \*(Aqpaul\*(Aq; + +SELECT SESSION_USER, CURRENT_USER; + + session_user | current_user +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\- + peter | paul +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +PostgreSQL +allows identifier syntax ("\fIrolename\fR"), while the SQL standard requires the role name to be written as a string literal\&. SQL does not allow this command during a transaction; +PostgreSQL +does not make this restriction because there is no reason to\&. The +SESSION +and +LOCAL +modifiers are a +PostgreSQL +extension, as is the +RESET +syntax\&. +.SH "SEE ALSO" +SET SESSION AUTHORIZATION (\fBSET_SESSION_AUTHORIZATION\fR(7)) diff --git a/doc/src/sgml/man7/SET_SESSION_AUTHORIZATION.7 b/doc/src/sgml/man7/SET_SESSION_AUTHORIZATION.7 new file mode 100644 index 0000000..641b48e --- /dev/null +++ b/doc/src/sgml/man7/SET_SESSION_AUTHORIZATION.7 @@ -0,0 +1,113 @@ +'\" t +.\" Title: SET SESSION AUTHORIZATION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SET SESSION AUTHORIZATION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SET_SESSION_AUTHORIZATION \- set the session user identifier and the current user identifier of the current session +.SH "SYNOPSIS" +.sp +.nf +SET [ SESSION | LOCAL ] SESSION AUTHORIZATION \fIuser_name\fR +SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT +RESET SESSION AUTHORIZATION +.fi +.SH "DESCRIPTION" +.PP +This command sets the session user identifier and the current user identifier of the current SQL session to be +\fIuser_name\fR\&. The user name can be written as either an identifier or a string literal\&. Using this command, it is possible, for example, to temporarily become an unprivileged user and later switch back to being a superuser\&. +.PP +The session user identifier is initially set to be the (possibly authenticated) user name provided by the client\&. The current user identifier is normally equal to the session user identifier, but might change temporarily in the context of +SECURITY DEFINER +functions and similar mechanisms; it can also be changed by +\fBSET ROLE\fR\&. The current user identifier is relevant for permission checking\&. +.PP +The session user identifier can be changed only if the initial session user (the +authenticated user) had the superuser privilege\&. Otherwise, the command is accepted only if it specifies the authenticated user name\&. +.PP +The +SESSION +and +LOCAL +modifiers act the same as for the regular +\fBSET\fR +command\&. +.PP +The +DEFAULT +and +RESET +forms reset the session and current user identifiers to be the originally authenticated user name\&. These forms can be executed by any user\&. +.SH "NOTES" +.PP +\fBSET SESSION AUTHORIZATION\fR +cannot be used within a +SECURITY DEFINER +function\&. +.SH "EXAMPLES" +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT SESSION_USER, CURRENT_USER; + + session_user | current_user +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\- + peter | peter + +SET SESSION AUTHORIZATION \*(Aqpaul\*(Aq; + +SELECT SESSION_USER, CURRENT_USER; + + session_user | current_user +\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\- + paul | paul +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The SQL standard allows some other expressions to appear in place of the literal +\fIuser_name\fR, but these options are not important in practice\&. +PostgreSQL +allows identifier syntax ("\fIusername\fR"), which SQL does not\&. SQL does not allow this command during a transaction; +PostgreSQL +does not make this restriction because there is no reason to\&. The +SESSION +and +LOCAL +modifiers are a +PostgreSQL +extension, as is the +RESET +syntax\&. +.PP +The privileges necessary to execute this command are left implementation\-defined by the standard\&. +.SH "SEE ALSO" +SET ROLE (\fBSET_ROLE\fR(7)) diff --git a/doc/src/sgml/man7/SET_TRANSACTION.7 b/doc/src/sgml/man7/SET_TRANSACTION.7 new file mode 100644 index 0000000..acbe84a --- /dev/null +++ b/doc/src/sgml/man7/SET_TRANSACTION.7 @@ -0,0 +1,242 @@ +'\" t +.\" Title: SET TRANSACTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SET TRANSACTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SET_TRANSACTION \- set the characteristics of the current transaction +.SH "SYNOPSIS" +.sp +.nf +SET TRANSACTION \fItransaction_mode\fR [, \&.\&.\&.] +SET TRANSACTION SNAPSHOT \fIsnapshot_id\fR +SET SESSION CHARACTERISTICS AS TRANSACTION \fItransaction_mode\fR [, \&.\&.\&.] + +where \fItransaction_mode\fR is one of: + + ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } + READ WRITE | READ ONLY + [ NOT ] DEFERRABLE +.fi +.SH "DESCRIPTION" +.PP +The +\fBSET TRANSACTION\fR +command sets the characteristics of the current transaction\&. It has no effect on any subsequent transactions\&. +\fBSET SESSION CHARACTERISTICS\fR +sets the default transaction characteristics for subsequent transactions of a session\&. These defaults can be overridden by +\fBSET TRANSACTION\fR +for an individual transaction\&. +.PP +The available transaction characteristics are the transaction isolation level, the transaction access mode (read/write or read\-only), and the deferrable mode\&. In addition, a snapshot can be selected, though only for the current transaction, not as a session default\&. +.PP +The isolation level of a transaction determines what data the transaction can see when other transactions are running concurrently: +.PP +READ COMMITTED +.RS 4 +A statement can only see rows committed before it began\&. This is the default\&. +.RE +.PP +REPEATABLE READ +.RS 4 +All statements of the current transaction can only see rows committed before the first query or data\-modification statement was executed in this transaction\&. +.RE +.PP +SERIALIZABLE +.RS 4 +All statements of the current transaction can only see rows committed before the first query or data\-modification statement was executed in this transaction\&. If a pattern of reads and writes among concurrent serializable transactions would create a situation which could not have occurred for any serial (one\-at\-a\-time) execution of those transactions, one of them will be rolled back with a +serialization_failure +error\&. +.RE +The SQL standard defines one additional level, +READ UNCOMMITTED\&. In +PostgreSQL +READ UNCOMMITTED +is treated as +READ COMMITTED\&. +.PP +The transaction isolation level cannot be changed after the first query or data\-modification statement (\fBSELECT\fR, +\fBINSERT\fR, +\fBDELETE\fR, +\fBUPDATE\fR, +\fBMERGE\fR, +\fBFETCH\fR, or +\fBCOPY\fR) of a transaction has been executed\&. See +Chapter\ \&13 +for more information about transaction isolation and concurrency control\&. +.PP +The transaction access mode determines whether the transaction is read/write or read\-only\&. Read/write is the default\&. When a transaction is read\-only, the following SQL commands are disallowed: +\fBINSERT\fR, +\fBUPDATE\fR, +\fBDELETE\fR, +\fBMERGE\fR, and +\fBCOPY FROM\fR +if the table they would write to is not a temporary table; all +CREATE, +ALTER, and +DROP +commands; +COMMENT, +GRANT, +REVOKE, +TRUNCATE; and +EXPLAIN ANALYZE +and +EXECUTE +if the command they would execute is among those listed\&. This is a high\-level notion of read\-only that does not prevent all writes to disk\&. +.PP +The +DEFERRABLE +transaction property has no effect unless the transaction is also +SERIALIZABLE +and +READ ONLY\&. When all three of these properties are selected for a transaction, the transaction may block when first acquiring its snapshot, after which it is able to run without the normal overhead of a +SERIALIZABLE +transaction and without any risk of contributing to or being canceled by a serialization failure\&. This mode is well suited for long\-running reports or backups\&. +.PP +The +SET TRANSACTION SNAPSHOT +command allows a new transaction to run with the same +snapshot +as an existing transaction\&. The pre\-existing transaction must have exported its snapshot with the +pg_export_snapshot +function (see +Section\ \&9.27.5)\&. That function returns a snapshot identifier, which must be given to +SET TRANSACTION SNAPSHOT +to specify which snapshot is to be imported\&. The identifier must be written as a string literal in this command, for example +\*(Aq00000003\-0000001B\-1\*(Aq\&. +SET TRANSACTION SNAPSHOT +can only be executed at the start of a transaction, before the first query or data\-modification statement (\fBSELECT\fR, +\fBINSERT\fR, +\fBDELETE\fR, +\fBUPDATE\fR, +\fBMERGE\fR, +\fBFETCH\fR, or +\fBCOPY\fR) of the transaction\&. Furthermore, the transaction must already be set to +SERIALIZABLE +or +REPEATABLE READ +isolation level (otherwise, the snapshot would be discarded immediately, since +READ COMMITTED +mode takes a new snapshot for each command)\&. If the importing transaction uses +SERIALIZABLE +isolation level, then the transaction that exported the snapshot must also use that isolation level\&. Also, a non\-read\-only serializable transaction cannot import a snapshot from a read\-only transaction\&. +.SH "NOTES" +.PP +If +\fBSET TRANSACTION\fR +is executed without a prior +\fBSTART TRANSACTION\fR +or +\fBBEGIN\fR, it emits a warning and otherwise has no effect\&. +.PP +It is possible to dispense with +\fBSET TRANSACTION\fR +by instead specifying the desired +\fItransaction_modes\fR +in +\fBBEGIN\fR +or +\fBSTART TRANSACTION\fR\&. But that option is not available for +\fBSET TRANSACTION SNAPSHOT\fR\&. +.PP +The session default transaction modes can also be set or examined via the configuration parameters +default_transaction_isolation, +default_transaction_read_only, and +default_transaction_deferrable\&. (In fact +\fBSET SESSION CHARACTERISTICS\fR +is just a verbose equivalent for setting these variables with +\fBSET\fR\&.) This means the defaults can be set in the configuration file, via +\fBALTER DATABASE\fR, etc\&. Consult +Chapter\ \&20 +for more information\&. +.PP +The current transaction\*(Aqs modes can similarly be set or examined via the configuration parameters +transaction_isolation, +transaction_read_only, and +transaction_deferrable\&. Setting one of these parameters acts the same as the corresponding +\fBSET TRANSACTION\fR +option, with the same restrictions on when it can be done\&. However, these parameters cannot be set in the configuration file, or from any source other than live SQL\&. +.SH "EXAMPLES" +.PP +To begin a new transaction with the same snapshot as an already existing transaction, first export the snapshot from the existing transaction\&. That will return the snapshot identifier, for example: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ; +SELECT pg_export_snapshot(); + pg_export_snapshot +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + 00000003\-0000001B\-1 +(1 row) +.fi +.if n \{\ +.RE +.\} +.sp +Then give the snapshot identifier in a +\fBSET TRANSACTION SNAPSHOT\fR +command at the beginning of the newly opened transaction: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN TRANSACTION ISOLATION LEVEL REPEATABLE READ; +SET TRANSACTION SNAPSHOT \*(Aq00000003\-0000001B\-1\*(Aq; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +These commands are defined in the +SQL +standard, except for the +DEFERRABLE +transaction mode and the +\fBSET TRANSACTION SNAPSHOT\fR +form, which are +PostgreSQL +extensions\&. +.PP +SERIALIZABLE +is the default transaction isolation level in the standard\&. In +PostgreSQL +the default is ordinarily +READ COMMITTED, but you can change it as mentioned above\&. +.PP +In the SQL standard, there is one other transaction characteristic that can be set with these commands: the size of the diagnostics area\&. This concept is specific to embedded SQL, and therefore is not implemented in the +PostgreSQL +server\&. +.PP +The SQL standard requires commas between successive +\fItransaction_modes\fR, but for historical reasons +PostgreSQL +allows the commas to be omitted\&. diff --git a/doc/src/sgml/man7/SHOW.7 b/doc/src/sgml/man7/SHOW.7 new file mode 100644 index 0000000..5b03064 --- /dev/null +++ b/doc/src/sgml/man7/SHOW.7 @@ -0,0 +1,167 @@ +'\" t +.\" Title: SHOW +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "SHOW" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +SHOW \- show the value of a run\-time parameter +.SH "SYNOPSIS" +.sp +.nf +SHOW \fIname\fR +SHOW ALL +.fi +.SH "DESCRIPTION" +.PP +\fBSHOW\fR +will display the current setting of run\-time parameters\&. These variables can be set using the +\fBSET\fR +statement, by editing the +postgresql\&.conf +configuration file, through the +\fBPGOPTIONS\fR +environmental variable (when using +libpq +or a +libpq\-based application), or through command\-line flags when starting the +\fBpostgres\fR +server\&. See +Chapter\ \&20 +for details\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name of a run\-time parameter\&. Available parameters are documented in +Chapter\ \&20 +and on the +\fBSET\fR(7) +reference page\&. In addition, there are a few parameters that can be shown but not set: +.PP +SERVER_VERSION +.RS 4 +Shows the server\*(Aqs version number\&. +.RE +.PP +SERVER_ENCODING +.RS 4 +Shows the server\-side character set encoding\&. At present, this parameter can be shown but not set, because the encoding is determined at database creation time\&. +.RE +.PP +LC_COLLATE +.RS 4 +Shows the database\*(Aqs locale setting for collation (text ordering)\&. At present, this parameter can be shown but not set, because the setting is determined at database creation time\&. +.RE +.PP +LC_CTYPE +.RS 4 +Shows the database\*(Aqs locale setting for character classification\&. At present, this parameter can be shown but not set, because the setting is determined at database creation time\&. +.RE +.PP +IS_SUPERUSER +.RS 4 +True if the current role has superuser privileges\&. +.RE +.RE +.PP +ALL +.RS 4 +Show the values of all configuration parameters, with descriptions\&. +.RE +.SH "NOTES" +.PP +The function +\fBcurrent_setting\fR +produces equivalent output; see +Section\ \&9.27.1\&. Also, the +pg_settings +system view produces the same information\&. +.SH "EXAMPLES" +.PP +Show the current setting of the parameter +\fIDateStyle\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SHOW DateStyle; + DateStyle +\-\-\-\-\-\-\-\-\-\-\- + ISO, MDY +(1 row) +.fi +.if n \{\ +.RE +.\} +.PP +Show the current setting of the parameter +\fIgeqo\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SHOW geqo; + geqo +\-\-\-\-\-\- + on +(1 row) +.fi +.if n \{\ +.RE +.\} +.PP +Show all settings: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SHOW ALL; + name | setting | description +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- + allow_system_table_mods | off | Allows modifications of the structure of \&.\&.\&. + \&. + \&. + \&. + xmloption | content | Sets whether XML data in implicit parsing \&.\&.\&. + zero_damaged_pages | off | Continues processing past damaged page headers\&. +(196 rows) +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The +\fBSHOW\fR +command is a +PostgreSQL +extension\&. +.SH "SEE ALSO" +\fBSET\fR(7), \fBRESET\fR(7) diff --git a/doc/src/sgml/man7/START_TRANSACTION.7 b/doc/src/sgml/man7/START_TRANSACTION.7 new file mode 100644 index 0000000..675dc9d --- /dev/null +++ b/doc/src/sgml/man7/START_TRANSACTION.7 @@ -0,0 +1,83 @@ +'\" t +.\" Title: START TRANSACTION +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "START TRANSACTION" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +START_TRANSACTION \- start a transaction block +.SH "SYNOPSIS" +.sp +.nf +START TRANSACTION [ \fItransaction_mode\fR [, \&.\&.\&.] ] + +where \fItransaction_mode\fR is one of: + + ISOLATION LEVEL { SERIALIZABLE | REPEATABLE READ | READ COMMITTED | READ UNCOMMITTED } + READ WRITE | READ ONLY + [ NOT ] DEFERRABLE +.fi +.SH "DESCRIPTION" +.PP +This command begins a new transaction block\&. If the isolation level, read/write mode, or deferrable mode is specified, the new transaction has those characteristics, as if +\fBSET TRANSACTION\fR +was executed\&. This is the same as the +\fBBEGIN\fR +command\&. +.SH "PARAMETERS" +.PP +Refer to +SET TRANSACTION (\fBSET_TRANSACTION\fR(7)) +for information on the meaning of the parameters to this statement\&. +.SH "COMPATIBILITY" +.PP +In the standard, it is not necessary to issue +\fBSTART TRANSACTION\fR +to start a transaction block: any SQL command implicitly begins a block\&. +PostgreSQL\*(Aqs behavior can be seen as implicitly issuing a +\fBCOMMIT\fR +after each command that does not follow +\fBSTART TRANSACTION\fR +(or +\fBBEGIN\fR), and it is therefore often called +\(lqautocommit\(rq\&. Other relational database systems might offer an autocommit feature as a convenience\&. +.PP +The +DEFERRABLE +\fItransaction_mode\fR +is a +PostgreSQL +language extension\&. +.PP +The SQL standard requires commas between successive +\fItransaction_modes\fR, but for historical reasons +PostgreSQL +allows the commas to be omitted\&. +.PP +See also the compatibility section of +SET TRANSACTION (\fBSET_TRANSACTION\fR(7))\&. +.SH "SEE ALSO" +\fBBEGIN\fR(7), \fBCOMMIT\fR(7), \fBROLLBACK\fR(7), \fBSAVEPOINT\fR(7), SET TRANSACTION (\fBSET_TRANSACTION\fR(7)) diff --git a/doc/src/sgml/man7/TABLE.7 b/doc/src/sgml/man7/TABLE.7 new file mode 100644 index 0000000..8e9105d --- /dev/null +++ b/doc/src/sgml/man7/TABLE.7 @@ -0,0 +1 @@ +.so man7/SELECT.7 diff --git a/doc/src/sgml/man7/TRUNCATE.7 b/doc/src/sgml/man7/TRUNCATE.7 new file mode 100644 index 0000000..6e547c7 --- /dev/null +++ b/doc/src/sgml/man7/TRUNCATE.7 @@ -0,0 +1,186 @@ +'\" t +.\" Title: TRUNCATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "TRUNCATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +TRUNCATE \- empty a table or set of tables +.SH "SYNOPSIS" +.sp +.nf +TRUNCATE [ TABLE ] [ ONLY ] \fIname\fR [ * ] [, \&.\&.\&. ] + [ RESTART IDENTITY | CONTINUE IDENTITY ] [ CASCADE | RESTRICT ] +.fi +.SH "DESCRIPTION" +.PP +\fBTRUNCATE\fR +quickly removes all rows from a set of tables\&. It has the same effect as an unqualified +\fBDELETE\fR +on each table, but since it does not actually scan the tables it is faster\&. Furthermore, it reclaims disk space immediately, rather than requiring a subsequent +\fBVACUUM\fR +operation\&. This is most useful on large tables\&. +.SH "PARAMETERS" +.PP +\fIname\fR +.RS 4 +The name (optionally schema\-qualified) of a table to truncate\&. If +ONLY +is specified before the table name, only that table is truncated\&. If +ONLY +is not specified, the table and all its descendant tables (if any) are truncated\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +RESTART IDENTITY +.RS 4 +Automatically restart sequences owned by columns of the truncated table(s)\&. +.RE +.PP +CONTINUE IDENTITY +.RS 4 +Do not change the values of sequences\&. This is the default\&. +.RE +.PP +CASCADE +.RS 4 +Automatically truncate all tables that have foreign\-key references to any of the named tables, or to any tables added to the group due to +CASCADE\&. +.RE +.PP +RESTRICT +.RS 4 +Refuse to truncate if any of the tables have foreign\-key references from tables that are not listed in the command\&. This is the default\&. +.RE +.SH "NOTES" +.PP +You must have the +TRUNCATE +privilege on a table to truncate it\&. +.PP +\fBTRUNCATE\fR +acquires an +ACCESS EXCLUSIVE +lock on each table it operates on, which blocks all other concurrent operations on the table\&. When +RESTART IDENTITY +is specified, any sequences that are to be restarted are likewise locked exclusively\&. If concurrent access to a table is required, then the +\fBDELETE\fR +command should be used instead\&. +.PP +\fBTRUNCATE\fR +cannot be used on a table that has foreign\-key references from other tables, unless all such tables are also truncated in the same command\&. Checking validity in such cases would require table scans, and the whole point is not to do one\&. The +CASCADE +option can be used to automatically include all dependent tables \(em but be very careful when using this option, or else you might lose data you did not intend to! Note in particular that when the table to be truncated is a partition, siblings partitions are left untouched, but cascading occurs to all referencing tables and all their partitions with no distinction\&. +.PP +\fBTRUNCATE\fR +will not fire any +ON DELETE +triggers that might exist for the tables\&. But it will fire +ON TRUNCATE +triggers\&. If +ON TRUNCATE +triggers are defined for any of the tables, then all +BEFORE TRUNCATE +triggers are fired before any truncation happens, and all +AFTER TRUNCATE +triggers are fired after the last truncation is performed and any sequences are reset\&. The triggers will fire in the order that the tables are to be processed (first those listed in the command, and then any that were added due to cascading)\&. +.PP +\fBTRUNCATE\fR +is not MVCC\-safe\&. After truncation, the table will appear empty to concurrent transactions, if they are using a snapshot taken before the truncation occurred\&. See +Section\ \&13.6 +for more details\&. +.PP +\fBTRUNCATE\fR +is transaction\-safe with respect to the data in the tables: the truncation will be safely rolled back if the surrounding transaction does not commit\&. +.PP +When +RESTART IDENTITY +is specified, the implied +\fBALTER SEQUENCE RESTART\fR +operations are also done transactionally; that is, they will be rolled back if the surrounding transaction does not commit\&. Be aware that if any additional sequence operations are done on the restarted sequences before the transaction rolls back, the effects of these operations on the sequences will be rolled back, but not their effects on +\fBcurrval()\fR; that is, after the transaction +\fBcurrval()\fR +will continue to reflect the last sequence value obtained inside the failed transaction, even though the sequence itself may no longer be consistent with that\&. This is similar to the usual behavior of +\fBcurrval()\fR +after a failed transaction\&. +.PP +\fBTRUNCATE\fR +can be used for foreign tables if supported by the foreign data wrapper, for instance, see +postgres_fdw\&. +.SH "EXAMPLES" +.PP +Truncate the tables +bigtable +and +fattable: +.sp +.if n \{\ +.RS 4 +.\} +.nf +TRUNCATE bigtable, fattable; +.fi +.if n \{\ +.RE +.\} +.PP +The same, and also reset any associated sequence generators: +.sp +.if n \{\ +.RS 4 +.\} +.nf +TRUNCATE bigtable, fattable RESTART IDENTITY; +.fi +.if n \{\ +.RE +.\} +.PP +Truncate the table +othertable, and cascade to any tables that reference +othertable +via foreign\-key constraints: +.sp +.if n \{\ +.RS 4 +.\} +.nf +TRUNCATE othertable CASCADE; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +The SQL:2008 standard includes a +\fBTRUNCATE\fR +command with the syntax +TRUNCATE TABLE \fItablename\fR\&. The clauses +CONTINUE IDENTITY/RESTART IDENTITY +also appear in that standard, but have slightly different though related meanings\&. Some of the concurrency behavior of this command is left implementation\-defined by the standard, so the above notes should be considered and compared with other implementations if necessary\&. +.SH "SEE ALSO" +\fBDELETE\fR(7) diff --git a/doc/src/sgml/man7/UNLISTEN.7 b/doc/src/sgml/man7/UNLISTEN.7 new file mode 100644 index 0000000..f73f740 --- /dev/null +++ b/doc/src/sgml/man7/UNLISTEN.7 @@ -0,0 +1,117 @@ +'\" t +.\" Title: UNLISTEN +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "UNLISTEN" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +UNLISTEN \- stop listening for a notification +.SH "SYNOPSIS" +.sp +.nf +UNLISTEN { \fIchannel\fR | * } +.fi +.SH "DESCRIPTION" +.PP +\fBUNLISTEN\fR +is used to remove an existing registration for +\fBNOTIFY\fR +events\&. +\fBUNLISTEN\fR +cancels any existing registration of the current +PostgreSQL +session as a listener on the notification channel named +\fIchannel\fR\&. The special wildcard +* +cancels all listener registrations for the current session\&. +.PP +\fBNOTIFY\fR(7) +contains a more extensive discussion of the use of +\fBLISTEN\fR +and +\fBNOTIFY\fR\&. +.SH "PARAMETERS" +.PP +\fIchannel\fR +.RS 4 +Name of a notification channel (any identifier)\&. +.RE +.PP +* +.RS 4 +All current listen registrations for this session are cleared\&. +.RE +.SH "NOTES" +.PP +You can unlisten something you were not listening for; no warning or error will appear\&. +.PP +At the end of each session, +\fBUNLISTEN *\fR +is automatically executed\&. +.PP +A transaction that has executed +\fBUNLISTEN\fR +cannot be prepared for two\-phase commit\&. +.SH "EXAMPLES" +.PP +To make a registration: +.sp +.if n \{\ +.RS 4 +.\} +.nf +LISTEN virtual; +NOTIFY virtual; +Asynchronous notification "virtual" received from server process with PID 8448\&. +.fi +.if n \{\ +.RE +.\} +.PP +Once +\fBUNLISTEN\fR +has been executed, further +\fBNOTIFY\fR +messages will be ignored: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UNLISTEN virtual; +NOTIFY virtual; +\-\- no NOTIFY event is received +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBUNLISTEN\fR +command in the SQL standard\&. +.SH "SEE ALSO" +\fBLISTEN\fR(7), \fBNOTIFY\fR(7) diff --git a/doc/src/sgml/man7/UPDATE.7 b/doc/src/sgml/man7/UPDATE.7 new file mode 100644 index 0000000..5dcbdf6 --- /dev/null +++ b/doc/src/sgml/man7/UPDATE.7 @@ -0,0 +1,473 @@ +'\" t +.\" Title: UPDATE +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "UPDATE" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +UPDATE \- update rows of a table +.SH "SYNOPSIS" +.sp +.nf +[ WITH [ RECURSIVE ] \fIwith_query\fR [, \&.\&.\&.] ] +UPDATE [ ONLY ] \fItable_name\fR [ * ] [ [ AS ] \fIalias\fR ] + SET { \fIcolumn_name\fR = { \fIexpression\fR | DEFAULT } | + ( \fIcolumn_name\fR [, \&.\&.\&.] ) = [ ROW ] ( { \fIexpression\fR | DEFAULT } [, \&.\&.\&.] ) | + ( \fIcolumn_name\fR [, \&.\&.\&.] ) = ( \fIsub\-SELECT\fR ) + } [, \&.\&.\&.] + [ FROM \fIfrom_item\fR [, \&.\&.\&.] ] + [ WHERE \fIcondition\fR | WHERE CURRENT OF \fIcursor_name\fR ] + [ RETURNING * | \fIoutput_expression\fR [ [ AS ] \fIoutput_name\fR ] [, \&.\&.\&.] ] +.fi +.SH "DESCRIPTION" +.PP +\fBUPDATE\fR +changes the values of the specified columns in all rows that satisfy the condition\&. Only the columns to be modified need be mentioned in the +SET +clause; columns not explicitly modified retain their previous values\&. +.PP +There are two ways to modify a table using information contained in other tables in the database: using sub\-selects, or specifying additional tables in the +FROM +clause\&. Which technique is more appropriate depends on the specific circumstances\&. +.PP +The optional +RETURNING +clause causes +\fBUPDATE\fR +to compute and return value(s) based on each row actually updated\&. Any expression using the table\*(Aqs columns, and/or columns of other tables mentioned in +FROM, can be computed\&. The new (post\-update) values of the table\*(Aqs columns are used\&. The syntax of the +RETURNING +list is identical to that of the output list of +\fBSELECT\fR\&. +.PP +You must have the +UPDATE +privilege on the table, or at least on the column(s) that are listed to be updated\&. You must also have the +SELECT +privilege on any column whose values are read in the +\fIexpressions\fR +or +\fIcondition\fR\&. +.SH "PARAMETERS" +.PP +\fIwith_query\fR +.RS 4 +The +WITH +clause allows you to specify one or more subqueries that can be referenced by name in the +\fBUPDATE\fR +query\&. See +Section\ \&7.8 +and +\fBSELECT\fR(7) +for details\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of the table to update\&. If +ONLY +is specified before the table name, matching rows are updated in the named table only\&. If +ONLY +is not specified, matching rows are also updated in any tables inheriting from the named table\&. Optionally, +* +can be specified after the table name to explicitly indicate that descendant tables are included\&. +.RE +.PP +\fIalias\fR +.RS 4 +A substitute name for the target table\&. When an alias is provided, it completely hides the actual name of the table\&. For example, given +UPDATE foo AS f, the remainder of the +\fBUPDATE\fR +statement must refer to this table as +f +not +foo\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a column in the table named by +\fItable_name\fR\&. The column name can be qualified with a subfield name or array subscript, if needed\&. Do not include the table\*(Aqs name in the specification of a target column \(em for example, +UPDATE table_name SET table_name\&.col = 1 +is invalid\&. +.RE +.PP +\fIexpression\fR +.RS 4 +An expression to assign to the column\&. The expression can use the old values of this and other columns in the table\&. +.RE +.PP +DEFAULT +.RS 4 +Set the column to its default value (which will be NULL if no specific default expression has been assigned to it)\&. An identity column will be set to a new value generated by the associated sequence\&. For a generated column, specifying this is permitted but merely specifies the normal behavior of computing the column from its generation expression\&. +.RE +.PP +\fIsub\-SELECT\fR +.RS 4 +A +SELECT +sub\-query that produces as many output columns as are listed in the parenthesized column list preceding it\&. The sub\-query must yield no more than one row when executed\&. If it yields one row, its column values are assigned to the target columns; if it yields no rows, NULL values are assigned to the target columns\&. The sub\-query can refer to old values of the current row of the table being updated\&. +.RE +.PP +\fIfrom_item\fR +.RS 4 +A table expression allowing columns from other tables to appear in the +WHERE +condition and update expressions\&. This uses the same syntax as the +FROM +clause of a +\fBSELECT\fR +statement; for example, an alias for the table name can be specified\&. Do not repeat the target table as a +\fIfrom_item\fR +unless you intend a self\-join (in which case it must appear with an alias in the +\fIfrom_item\fR)\&. +.RE +.PP +\fIcondition\fR +.RS 4 +An expression that returns a value of type +boolean\&. Only rows for which this expression returns +true +will be updated\&. +.RE +.PP +\fIcursor_name\fR +.RS 4 +The name of the cursor to use in a +WHERE CURRENT OF +condition\&. The row to be updated is the one most recently fetched from this cursor\&. The cursor must be a non\-grouping query on the +\fBUPDATE\fR\*(Aqs target table\&. Note that +WHERE CURRENT OF +cannot be specified together with a Boolean condition\&. See +\fBDECLARE\fR(7) +for more information about using cursors with +WHERE CURRENT OF\&. +.RE +.PP +\fIoutput_expression\fR +.RS 4 +An expression to be computed and returned by the +\fBUPDATE\fR +command after each row is updated\&. The expression can use any column names of the table named by +\fItable_name\fR +or table(s) listed in +FROM\&. Write +* +to return all columns\&. +.RE +.PP +\fIoutput_name\fR +.RS 4 +A name to use for a returned column\&. +.RE +.SH "OUTPUTS" +.PP +On successful completion, an +\fBUPDATE\fR +command returns a command tag of the form +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE \fIcount\fR +.fi +.if n \{\ +.RE +.\} +.sp +The +\fIcount\fR +is the number of rows updated, including matched rows whose values did not change\&. Note that the number may be less than the number of rows that matched the +\fIcondition\fR +when updates were suppressed by a +BEFORE UPDATE +trigger\&. If +\fIcount\fR +is 0, no rows were updated by the query (this is not considered an error)\&. +.PP +If the +\fBUPDATE\fR +command contains a +RETURNING +clause, the result will be similar to that of a +\fBSELECT\fR +statement containing the columns and values defined in the +RETURNING +list, computed over the row(s) updated by the command\&. +.SH "NOTES" +.PP +When a +FROM +clause is present, what essentially happens is that the target table is joined to the tables mentioned in the +\fIfrom_item\fR +list, and each output row of the join represents an update operation for the target table\&. When using +FROM +you should ensure that the join produces at most one output row for each row to be modified\&. In other words, a target row shouldn\*(Aqt join to more than one row from the other table(s)\&. If it does, then only one of the join rows will be used to update the target row, but which one will be used is not readily predictable\&. +.PP +Because of this indeterminacy, referencing other tables only within sub\-selects is safer, though often harder to read and slower than using a join\&. +.PP +In the case of a partitioned table, updating a row might cause it to no longer satisfy the partition constraint of the containing partition\&. In that case, if there is some other partition in the partition tree for which this row satisfies its partition constraint, then the row is moved to that partition\&. If there is no such partition, an error will occur\&. Behind the scenes, the row movement is actually a +\fBDELETE\fR +and +\fBINSERT\fR +operation\&. +.PP +There is a possibility that a concurrent +\fBUPDATE\fR +or +\fBDELETE\fR +on the row being moved will get a serialization failure error\&. Suppose session 1 is performing an +\fBUPDATE\fR +on a partition key, and meanwhile a concurrent session 2 for which this row is visible performs an +\fBUPDATE\fR +or +\fBDELETE\fR +operation on this row\&. In such case, session 2\*(Aqs +\fBUPDATE\fR +or +\fBDELETE\fR +will detect the row movement and raise a serialization failure error (which always returns with an SQLSTATE code \*(Aq40001\*(Aq)\&. Applications may wish to retry the transaction if this occurs\&. In the usual case where the table is not partitioned, or where there is no row movement, session 2 would have identified the newly updated row and carried out the +\fBUPDATE\fR/\fBDELETE\fR +on this new row version\&. +.PP +Note that while rows can be moved from local partitions to a foreign\-table partition (provided the foreign data wrapper supports tuple routing), they cannot be moved from a foreign\-table partition to another partition\&. +.PP +An attempt of moving a row from one partition to another will fail if a foreign key is found to directly reference an ancestor of the source partition that is not the same as the ancestor that\*(Aqs mentioned in the +\fBUPDATE\fR +query\&. +.SH "EXAMPLES" +.PP +Change the word +Drama +to +Dramatic +in the column +kind +of the table +films: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE films SET kind = \*(AqDramatic\*(Aq WHERE kind = \*(AqDrama\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Adjust temperature entries and reset precipitation to its default value in one row of the table +weather: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT + WHERE city = \*(AqSan Francisco\*(Aq AND date = \*(Aq2003\-07\-03\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Perform the same operation and return the updated entries: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE weather SET temp_lo = temp_lo+1, temp_hi = temp_lo+15, prcp = DEFAULT + WHERE city = \*(AqSan Francisco\*(Aq AND date = \*(Aq2003\-07\-03\*(Aq + RETURNING temp_lo, temp_hi, prcp; +.fi +.if n \{\ +.RE +.\} +.PP +Use the alternative column\-list syntax to do the same update: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE weather SET (temp_lo, temp_hi, prcp) = (temp_lo+1, temp_lo+15, DEFAULT) + WHERE city = \*(AqSan Francisco\*(Aq AND date = \*(Aq2003\-07\-03\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +Increment the sales count of the salesperson who manages the account for Acme Corporation, using the +FROM +clause syntax: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE employees SET sales_count = sales_count + 1 FROM accounts + WHERE accounts\&.name = \*(AqAcme Corporation\*(Aq + AND employees\&.id = accounts\&.sales_person; +.fi +.if n \{\ +.RE +.\} +.PP +Perform the same operation, using a sub\-select in the +WHERE +clause: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE employees SET sales_count = sales_count + 1 WHERE id = + (SELECT sales_person FROM accounts WHERE name = \*(AqAcme Corporation\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +Update contact names in an accounts table to match the currently assigned salespeople: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE accounts SET (contact_first_name, contact_last_name) = + (SELECT first_name, last_name FROM employees + WHERE employees\&.id = accounts\&.sales_person); +.fi +.if n \{\ +.RE +.\} +.sp +A similar result could be accomplished with a join: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE accounts SET contact_first_name = first_name, + contact_last_name = last_name + FROM employees WHERE employees\&.id = accounts\&.sales_person; +.fi +.if n \{\ +.RE +.\} +.sp +However, the second query may give unexpected results if +employees\&.id +is not a unique key, whereas the first query is guaranteed to raise an error if there are multiple +id +matches\&. Also, if there is no match for a particular +accounts\&.sales_person +entry, the first query will set the corresponding name fields to NULL, whereas the second query will not update that row at all\&. +.PP +Update statistics in a summary table to match the current data: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE summary s SET (sum_x, sum_y, avg_x, avg_y) = + (SELECT sum(x), sum(y), avg(x), avg(y) FROM data d + WHERE d\&.group_id = s\&.group_id); +.fi +.if n \{\ +.RE +.\} +.PP +Attempt to insert a new stock item along with the quantity of stock\&. If the item already exists, instead update the stock count of the existing item\&. To do this without failing the entire transaction, use savepoints: +.sp +.if n \{\ +.RS 4 +.\} +.nf +BEGIN; +\-\- other operations +SAVEPOINT sp1; +INSERT INTO wines VALUES(\*(AqChateau Lafite 2003\*(Aq, \*(Aq24\*(Aq); +\-\- Assume the above fails because of a unique key violation, +\-\- so now we issue these commands: +ROLLBACK TO sp1; +UPDATE wines SET stock = stock + 24 WHERE winename = \*(AqChateau Lafite 2003\*(Aq; +\-\- continue with other operations, and eventually +COMMIT; +.fi +.if n \{\ +.RE +.\} +.PP +Change the +kind +column of the table +films +in the row on which the cursor +c_films +is currently positioned: +.sp +.if n \{\ +.RS 4 +.\} +.nf +UPDATE films SET kind = \*(AqDramatic\*(Aq WHERE CURRENT OF c_films; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +This command conforms to the +SQL +standard, except that the +FROM +and +RETURNING +clauses are +PostgreSQL +extensions, as is the ability to use +WITH +with +\fBUPDATE\fR\&. +.PP +Some other database systems offer a +FROM +option in which the target table is supposed to be listed again within +FROM\&. That is not how +PostgreSQL +interprets +FROM\&. Be careful when porting applications that use this extension\&. +.PP +According to the standard, the source value for a parenthesized sub\-list of target column names can be any row\-valued expression yielding the correct number of columns\&. +PostgreSQL +only allows the source value to be a +row constructor +or a sub\-SELECT\&. An individual column\*(Aqs updated value can be specified as +DEFAULT +in the row\-constructor case, but not inside a sub\-SELECT\&. diff --git a/doc/src/sgml/man7/VACUUM.7 b/doc/src/sgml/man7/VACUUM.7 new file mode 100644 index 0000000..7e7d7f2 --- /dev/null +++ b/doc/src/sgml/man7/VACUUM.7 @@ -0,0 +1,364 @@ +'\" t +.\" Title: VACUUM +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "VACUUM" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +VACUUM \- garbage\-collect and optionally analyze a database +.SH "SYNOPSIS" +.sp +.nf +VACUUM [ ( \fIoption\fR [, \&.\&.\&.] ) ] [ \fItable_and_columns\fR [, \&.\&.\&.] ] +VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ \fItable_and_columns\fR [, \&.\&.\&.] ] + +where \fIoption\fR can be one of: + + FULL [ \fIboolean\fR ] + FREEZE [ \fIboolean\fR ] + VERBOSE [ \fIboolean\fR ] + ANALYZE [ \fIboolean\fR ] + DISABLE_PAGE_SKIPPING [ \fIboolean\fR ] + SKIP_LOCKED [ \fIboolean\fR ] + INDEX_CLEANUP { AUTO | ON | OFF } + PROCESS_TOAST [ \fIboolean\fR ] + TRUNCATE [ \fIboolean\fR ] + PARALLEL \fIinteger\fR + +and \fItable_and_columns\fR is: + + \fItable_name\fR [ ( \fIcolumn_name\fR [, \&.\&.\&.] ) ] +.fi +.SH "DESCRIPTION" +.PP +\fBVACUUM\fR +reclaims storage occupied by dead tuples\&. In normal +PostgreSQL +operation, tuples that are deleted or obsoleted by an update are not physically removed from their table; they remain present until a +\fBVACUUM\fR +is done\&. Therefore it\*(Aqs necessary to do +\fBVACUUM\fR +periodically, especially on frequently\-updated tables\&. +.PP +Without a +\fItable_and_columns\fR +list, +\fBVACUUM\fR +processes every table and materialized view in the current database that the current user has permission to vacuum\&. With a list, +\fBVACUUM\fR +processes only those table(s)\&. +.PP +\fBVACUUM ANALYZE\fR +performs a +\fBVACUUM\fR +and then an +\fBANALYZE\fR +for each selected table\&. This is a handy combination form for routine maintenance scripts\&. See +\fBANALYZE\fR(7) +for more details about its processing\&. +.PP +Plain +\fBVACUUM\fR +(without +FULL) simply reclaims space and makes it available for re\-use\&. This form of the command can operate in parallel with normal reading and writing of the table, as an exclusive lock is not obtained\&. However, extra space is not returned to the operating system (in most cases); it\*(Aqs just kept available for re\-use within the same table\&. It also allows us to leverage multiple CPUs in order to process indexes\&. This feature is known as +parallel vacuum\&. To disable this feature, one can use +PARALLEL +option and specify parallel workers as zero\&. +\fBVACUUM FULL\fR +rewrites the entire contents of the table into a new disk file with no extra space, allowing unused space to be returned to the operating system\&. This form is much slower and requires an +ACCESS EXCLUSIVE +lock on each table while it is being processed\&. +.PP +When the option list is surrounded by parentheses, the options can be written in any order\&. Without parentheses, options must be specified in exactly the order shown above\&. The parenthesized syntax was added in +PostgreSQL +9\&.0; the unparenthesized syntax is deprecated\&. +.SH "PARAMETERS" +.PP +FULL +.RS 4 +Selects +\(lqfull\(rq +vacuum, which can reclaim more space, but takes much longer and exclusively locks the table\&. This method also requires extra disk space, since it writes a new copy of the table and doesn\*(Aqt release the old copy until the operation is complete\&. Usually this should only be used when a significant amount of space needs to be reclaimed from within the table\&. +.RE +.PP +FREEZE +.RS 4 +Selects aggressive +\(lqfreezing\(rq +of tuples\&. Specifying +FREEZE +is equivalent to performing +\fBVACUUM\fR +with the +vacuum_freeze_min_age +and +vacuum_freeze_table_age +parameters set to zero\&. Aggressive freezing is always performed when the table is rewritten, so this option is redundant when +FULL +is specified\&. +.RE +.PP +VERBOSE +.RS 4 +Prints a detailed vacuum activity report for each table\&. +.RE +.PP +ANALYZE +.RS 4 +Updates statistics used by the planner to determine the most efficient way to execute a query\&. +.RE +.PP +DISABLE_PAGE_SKIPPING +.RS 4 +Normally, +\fBVACUUM\fR +will skip pages based on the +visibility map\&. Pages where all tuples are known to be frozen can always be skipped, and those where all tuples are known to be visible to all transactions may be skipped except when performing an aggressive vacuum\&. Furthermore, except when performing an aggressive vacuum, some pages may be skipped in order to avoid waiting for other sessions to finish using them\&. This option disables all page\-skipping behavior, and is intended to be used only when the contents of the visibility map are suspect, which should happen only if there is a hardware or software issue causing database corruption\&. +.RE +.PP +SKIP_LOCKED +.RS 4 +Specifies that +\fBVACUUM\fR +should not wait for any conflicting locks to be released when beginning work on a relation: if a relation cannot be locked immediately without waiting, the relation is skipped\&. Note that even with this option, +\fBVACUUM\fR +may still block when opening the relation\*(Aqs indexes\&. Additionally, +\fBVACUUM ANALYZE\fR +may still block when acquiring sample rows from partitions, table inheritance children, and some types of foreign tables\&. Also, while +\fBVACUUM\fR +ordinarily processes all partitions of specified partitioned tables, this option will cause +\fBVACUUM\fR +to skip all partitions if there is a conflicting lock on the partitioned table\&. +.RE +.PP +INDEX_CLEANUP +.RS 4 +Normally, +\fBVACUUM\fR +will skip index vacuuming when there are very few dead tuples in the table\&. The cost of processing all of the table\*(Aqs indexes is expected to greatly exceed the benefit of removing dead index tuples when this happens\&. This option can be used to force +\fBVACUUM\fR +to process indexes when there are more than zero dead tuples\&. The default is +AUTO, which allows +\fBVACUUM\fR +to skip index vacuuming when appropriate\&. If +INDEX_CLEANUP +is set to +ON, +\fBVACUUM\fR +will conservatively remove all dead tuples from indexes\&. This may be useful for backwards compatibility with earlier releases of +PostgreSQL +where this was the standard behavior\&. +.sp +INDEX_CLEANUP +can also be set to +OFF +to force +\fBVACUUM\fR +to +\fIalways\fR +skip index vacuuming, even when there are many dead tuples in the table\&. This may be useful when it is necessary to make +\fBVACUUM\fR +run as quickly as possible to avoid imminent transaction ID wraparound (see +Section\ \&25.1.5)\&. However, the wraparound failsafe mechanism controlled by +vacuum_failsafe_age +will generally trigger automatically to avoid transaction ID wraparound failure, and should be preferred\&. If index cleanup is not performed regularly, performance may suffer, because as the table is modified indexes will accumulate dead tuples and the table itself will accumulate dead line pointers that cannot be removed until index cleanup is completed\&. +.sp +This option has no effect for tables that have no index and is ignored if the +FULL +option is used\&. It also has no effect on the transaction ID wraparound failsafe mechanism\&. When triggered it will skip index vacuuming, even when +INDEX_CLEANUP +is set to +ON\&. +.RE +.PP +PROCESS_TOAST +.RS 4 +Specifies that +\fBVACUUM\fR +should attempt to process the corresponding +TOAST +table for each relation, if one exists\&. This is usually the desired behavior and is the default\&. Setting this option to false may be useful when it is only necessary to vacuum the main relation\&. This option is required when the +FULL +option is used\&. +.RE +.PP +TRUNCATE +.RS 4 +Specifies that +\fBVACUUM\fR +should attempt to truncate off any empty pages at the end of the table and allow the disk space for the truncated pages to be returned to the operating system\&. This is normally the desired behavior and is the default unless the +vacuum_truncate +option has been set to false for the table to be vacuumed\&. Setting this option to false may be useful to avoid +ACCESS EXCLUSIVE +lock on the table that the truncation requires\&. This option is ignored if the +FULL +option is used\&. +.RE +.PP +PARALLEL +.RS 4 +Perform index vacuum and index cleanup phases of +\fBVACUUM\fR +in parallel using +\fIinteger\fR +background workers (for the details of each vacuum phase, please refer to +Table\ \&28.41)\&. The number of workers used to perform the operation is equal to the number of indexes on the relation that support parallel vacuum which is limited by the number of workers specified with +PARALLEL +option if any which is further limited by +max_parallel_maintenance_workers\&. An index can participate in parallel vacuum if and only if the size of the index is more than +min_parallel_index_scan_size\&. Please note that it is not guaranteed that the number of parallel workers specified in +\fIinteger\fR +will be used during execution\&. It is possible for a vacuum to run with fewer workers than specified, or even with no workers at all\&. Only one worker can be used per index\&. So parallel workers are launched only when there are at least +2 +indexes in the table\&. Workers for vacuum are launched before the start of each phase and exit at the end of the phase\&. These behaviors might change in a future release\&. This option can\*(Aqt be used with the +FULL +option\&. +.RE +.PP +\fIboolean\fR +.RS 4 +Specifies whether the selected option should be turned on or off\&. You can write +TRUE, +ON, or +1 +to enable the option, and +FALSE, +OFF, or +0 +to disable it\&. The +\fIboolean\fR +value can also be omitted, in which case +TRUE +is assumed\&. +.RE +.PP +\fIinteger\fR +.RS 4 +Specifies a non\-negative integer value passed to the selected option\&. +.RE +.PP +\fItable_name\fR +.RS 4 +The name (optionally schema\-qualified) of a specific table or materialized view to vacuum\&. If the specified table is a partitioned table, all of its leaf partitions are vacuumed\&. +.RE +.PP +\fIcolumn_name\fR +.RS 4 +The name of a specific column to analyze\&. Defaults to all columns\&. If a column list is specified, +ANALYZE +must also be specified\&. +.RE +.SH "OUTPUTS" +.PP +When +VERBOSE +is specified, +\fBVACUUM\fR +emits progress messages to indicate which table is currently being processed\&. Various statistics about the tables are printed as well\&. +.SH "NOTES" +.PP +To vacuum a table, one must ordinarily be the table\*(Aqs owner or a superuser\&. However, database owners are allowed to vacuum all tables in their databases, except shared catalogs\&. (The restriction for shared catalogs means that a true database\-wide +\fBVACUUM\fR +can only be performed by a superuser\&.) +\fBVACUUM\fR +will skip over any tables that the calling user does not have permission to vacuum\&. +.PP +\fBVACUUM\fR +cannot be executed inside a transaction block\&. +.PP +For tables with +GIN +indexes, +\fBVACUUM\fR +(in any form) also completes any pending index insertions, by moving pending index entries to the appropriate places in the main +GIN +index structure\&. See +Section\ \&70.4.1 +for details\&. +.PP +We recommend that all databases be vacuumed regularly in order to remove dead rows\&. +PostgreSQL +includes an +\(lqautovacuum\(rq +facility which can automate routine vacuum maintenance\&. For more information about automatic and manual vacuuming, see +Section\ \&25.1\&. +.PP +The +\fBFULL\fR +option is not recommended for routine use, but might be useful in special cases\&. An example is when you have deleted or updated most of the rows in a table and would like the table to physically shrink to occupy less disk space and allow faster table scans\&. +\fBVACUUM FULL\fR +will usually shrink the table more than a plain +\fBVACUUM\fR +would\&. +.PP +The +\fBPARALLEL\fR +option is used only for vacuum purposes\&. If this option is specified with the +\fBANALYZE\fR +option, it does not affect +\fBANALYZE\fR\&. +.PP +\fBVACUUM\fR +causes a substantial increase in I/O traffic, which might cause poor performance for other active sessions\&. Therefore, it is sometimes advisable to use the cost\-based vacuum delay feature\&. For parallel vacuum, each worker sleeps in proportion to the work done by that worker\&. See +Section\ \&20.4.4 +for details\&. +.PP +Each backend running +\fBVACUUM\fR +without the +FULL +option will report its progress in the +pg_stat_progress_vacuum +view\&. Backends running +\fBVACUUM FULL\fR +will instead report their progress in the +pg_stat_progress_cluster +view\&. See +Section\ \&28.4.3 +and +Section\ \&28.4.4 +for details\&. +.SH "EXAMPLES" +.PP +To clean a single table +onek, analyze it for the optimizer and print a detailed vacuum activity report: +.sp +.if n \{\ +.RS 4 +.\} +.nf +VACUUM (VERBOSE, ANALYZE) onek; +.fi +.if n \{\ +.RE +.\} +.SH "COMPATIBILITY" +.PP +There is no +\fBVACUUM\fR +statement in the SQL standard\&. +.SH "SEE ALSO" +\fBvacuumdb\fR(1), Section\ \&20.4.4, Section\ \&25.1.6, Section\ \&28.4.3, Section\ \&28.4.4 diff --git a/doc/src/sgml/man7/VALUES.7 b/doc/src/sgml/man7/VALUES.7 new file mode 100644 index 0000000..0025e6d --- /dev/null +++ b/doc/src/sgml/man7/VALUES.7 @@ -0,0 +1,292 @@ +'\" t +.\" Title: VALUES +.\" Author: The PostgreSQL Global Development Group +.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> +.\" Date: 2023 +.\" Manual: PostgreSQL 15.5 Documentation +.\" Source: PostgreSQL 15.5 +.\" Language: English +.\" +.TH "VALUES" "7" "2023" "PostgreSQL 15.5" "PostgreSQL 15.5 Documentation" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +VALUES \- compute a set of rows +.SH "SYNOPSIS" +.sp +.nf +VALUES ( \fIexpression\fR [, \&.\&.\&.] ) [, \&.\&.\&.] + [ ORDER BY \fIsort_expression\fR [ ASC | DESC | USING \fIoperator\fR ] [, \&.\&.\&.] ] + [ LIMIT { \fIcount\fR | ALL } ] + [ OFFSET \fIstart\fR [ ROW | ROWS ] ] + [ FETCH { FIRST | NEXT } [ \fIcount\fR ] { ROW | ROWS } ONLY ] +.fi +.SH "DESCRIPTION" +.PP +\fBVALUES\fR +computes a row value or set of row values specified by value expressions\&. It is most commonly used to generate a +\(lqconstant table\(rq +within a larger command, but it can be used on its own\&. +.PP +When more than one row is specified, all the rows must have the same number of elements\&. The data types of the resulting table\*(Aqs columns are determined by combining the explicit or inferred types of the expressions appearing in that column, using the same rules as for +UNION +(see +Section\ \&10.5)\&. +.PP +Within larger commands, +\fBVALUES\fR +is syntactically allowed anywhere that +\fBSELECT\fR +is\&. Because it is treated like a +\fBSELECT\fR +by the grammar, it is possible to use the +ORDER BY, +LIMIT +(or equivalently +FETCH FIRST), and +OFFSET +clauses with a +\fBVALUES\fR +command\&. +.SH "PARAMETERS" +.PP +\fIexpression\fR +.RS 4 +A constant or expression to compute and insert at the indicated place in the resulting table (set of rows)\&. In a +\fBVALUES\fR +list appearing at the top level of an +\fBINSERT\fR, an +\fIexpression\fR +can be replaced by +DEFAULT +to indicate that the destination column\*(Aqs default value should be inserted\&. +DEFAULT +cannot be used when +\fBVALUES\fR +appears in other contexts\&. +.RE +.PP +\fIsort_expression\fR +.RS 4 +An expression or integer constant indicating how to sort the result rows\&. This expression can refer to the columns of the +\fBVALUES\fR +result as +column1, +column2, etc\&. For more details see +ORDER BY Clause +in the +\fBSELECT\fR(7) +documentation\&. +.RE +.PP +\fIoperator\fR +.RS 4 +A sorting operator\&. For details see +ORDER BY Clause +in the +\fBSELECT\fR(7) +documentation\&. +.RE +.PP +\fIcount\fR +.RS 4 +The maximum number of rows to return\&. For details see +LIMIT Clause +in the +\fBSELECT\fR(7) +documentation\&. +.RE +.PP +\fIstart\fR +.RS 4 +The number of rows to skip before starting to return rows\&. For details see +LIMIT Clause +in the +\fBSELECT\fR(7) +documentation\&. +.RE +.SH "NOTES" +.PP +\fBVALUES\fR +lists with very large numbers of rows should be avoided, as you might encounter out\-of\-memory failures or poor performance\&. +\fBVALUES\fR +appearing within +\fBINSERT\fR +is a special case (because the desired column types are known from the +\fBINSERT\fR\*(Aqs target table, and need not be inferred by scanning the +\fBVALUES\fR +list), so it can handle larger lists than are practical in other contexts\&. +.SH "EXAMPLES" +.PP +A bare +\fBVALUES\fR +command: +.sp +.if n \{\ +.RS 4 +.\} +.nf +VALUES (1, \*(Aqone\*(Aq), (2, \*(Aqtwo\*(Aq), (3, \*(Aqthree\*(Aq); +.fi +.if n \{\ +.RE +.\} +.sp +This will return a table of two columns and three rows\&. It\*(Aqs effectively equivalent to: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT 1 AS column1, \*(Aqone\*(Aq AS column2 +UNION ALL +SELECT 2, \*(Aqtwo\*(Aq +UNION ALL +SELECT 3, \*(Aqthree\*(Aq; +.fi +.if n \{\ +.RE +.\} +.PP +More usually, +\fBVALUES\fR +is used within a larger SQL command\&. The most common use is in +\fBINSERT\fR: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films (code, title, did, date_prod, kind) + VALUES (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, \*(Aq1961\-06\-16\*(Aq, \*(AqDrama\*(Aq); +.fi +.if n \{\ +.RE +.\} +.PP +In the context of +\fBINSERT\fR, entries of a +\fBVALUES\fR +list can be +DEFAULT +to indicate that the column default should be used here instead of specifying a value: +.sp +.if n \{\ +.RS 4 +.\} +.nf +INSERT INTO films VALUES + (\*(AqUA502\*(Aq, \*(AqBananas\*(Aq, 105, DEFAULT, \*(AqComedy\*(Aq, \*(Aq82 minutes\*(Aq), + (\*(AqT_601\*(Aq, \*(AqYojimbo\*(Aq, 106, DEFAULT, \*(AqDrama\*(Aq, DEFAULT); +.fi +.if n \{\ +.RE +.\} +.PP +\fBVALUES\fR +can also be used where a sub\-\fBSELECT\fR +might be written, for example in a +FROM +clause: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT f\&.* + FROM films f, (VALUES(\*(AqMGM\*(Aq, \*(AqHorror\*(Aq), (\*(AqUA\*(Aq, \*(AqSci\-Fi\*(Aq)) AS t (studio, kind) + WHERE f\&.studio = t\&.studio AND f\&.kind = t\&.kind; + +UPDATE employees SET salary = salary * v\&.increase + FROM (VALUES(1, 200000, 1\&.2), (2, 400000, 1\&.4)) AS v (depno, target, increase) + WHERE employees\&.depno = v\&.depno AND employees\&.sales >= v\&.target; +.fi +.if n \{\ +.RE +.\} +.sp +Note that an +AS +clause is required when +\fBVALUES\fR +is used in a +FROM +clause, just as is true for +\fBSELECT\fR\&. It is not required that the +AS +clause specify names for all the columns, but it\*(Aqs good practice to do so\&. (The default column names for +\fBVALUES\fR +are +column1, +column2, etc\&. in +PostgreSQL, but these names might be different in other database systems\&.) +.PP +When +\fBVALUES\fR +is used in +\fBINSERT\fR, the values are all automatically coerced to the data type of the corresponding destination column\&. When it\*(Aqs used in other contexts, it might be necessary to specify the correct data type\&. If the entries are all quoted literal constants, coercing the first is sufficient to determine the assumed type for all: +.sp +.if n \{\ +.RS 4 +.\} +.nf +SELECT * FROM machines +WHERE ip_address IN (VALUES(\*(Aq192\&.168\&.0\&.1\*(Aq::inet), (\*(Aq192\&.168\&.0\&.10\*(Aq), (\*(Aq192\&.168\&.1\&.43\*(Aq)); +.fi +.if n \{\ +.RE +.\} +.if n \{\ +.sp +.\} +.RS 4 +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.ps +1 +\fBTip\fR +.ps -1 +.br +.PP +For simple +IN +tests, it\*(Aqs better to rely on the +list\-of\-scalars +form of +IN +than to write a +\fBVALUES\fR +query as shown above\&. The list of scalars method requires less writing and is often more efficient\&. +.sp .5v +.RE +.SH "COMPATIBILITY" +.PP +\fBVALUES\fR +conforms to the SQL standard\&. +LIMIT +and +OFFSET +are +PostgreSQL +extensions; see also under +\fBSELECT\fR(7)\&. +.SH "SEE ALSO" +\fBINSERT\fR(7), \fBSELECT\fR(7) diff --git a/doc/src/sgml/man7/WITH.7 b/doc/src/sgml/man7/WITH.7 new file mode 100644 index 0000000..8e9105d --- /dev/null +++ b/doc/src/sgml/man7/WITH.7 @@ -0,0 +1 @@ +.so man7/SELECT.7 |