diff options
Diffstat (limited to 'doc/src/sgml/ref')
182 files changed, 3770 insertions, 3770 deletions
diff --git a/doc/src/sgml/ref/abort.sgml b/doc/src/sgml/ref/abort.sgml index ed9332c395b..285d0d4ac65 100644 --- a/doc/src/sgml/ref/abort.sgml +++ b/doc/src/sgml/ref/abort.sgml @@ -63,7 +63,7 @@ ABORT [ WORK | TRANSACTION ] </para> <para> - Issuing <command>ABORT</> outside of a transaction block + Issuing <command>ABORT</command> outside of a transaction block emits a warning and otherwise has no effect. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_aggregate.sgml b/doc/src/sgml/ref/alter_aggregate.sgml index 7b7616ca014..43f0a1609b9 100644 --- a/doc/src/sgml/ref/alter_aggregate.sgml +++ b/doc/src/sgml/ref/alter_aggregate.sgml @@ -43,7 +43,7 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu </para> <para> - You must own the aggregate function to use <command>ALTER AGGREGATE</>. + You must own the aggregate function to use <command>ALTER AGGREGATE</command>. To change the schema of an aggregate function, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -73,8 +73,8 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu <listitem> <para> - The mode of an argument: <literal>IN</> or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal> or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. </para> </listitem> </varlistentry> @@ -97,10 +97,10 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu <listitem> <para> An input data type on which the aggregate function operates. - To reference a zero-argument aggregate function, write <literal>*</> + To reference a zero-argument aggregate function, write <literal>*</literal> in place of the list of argument specifications. To reference an ordered-set aggregate function, write - <literal>ORDER BY</> between the direct and aggregated argument + <literal>ORDER BY</literal> between the direct and aggregated argument specifications. </para> </listitem> @@ -140,13 +140,13 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>aggregate_signatu <para> The recommended syntax for referencing an ordered-set aggregate - is to write <literal>ORDER BY</> between the direct and aggregated + is to write <literal>ORDER BY</literal> between the direct and aggregated argument specifications, in the same style as in <xref linkend="sql-createaggregate">. However, it will also work to - omit <literal>ORDER BY</> and just run the direct and aggregated + omit <literal>ORDER BY</literal> and just run the direct and aggregated argument specifications into a single list. In this abbreviated form, - if <literal>VARIADIC "any"</> was used in both the direct and - aggregated argument lists, write <literal>VARIADIC "any"</> only once. + if <literal>VARIADIC "any"</literal> was used in both the direct and + aggregated argument lists, write <literal>VARIADIC "any"</literal> only once. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml index 30e8c756a12..9d77ee5c2c3 100644 --- a/doc/src/sgml/ref/alter_collation.sgml +++ b/doc/src/sgml/ref/alter_collation.sgml @@ -38,7 +38,7 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche </para> <para> - You must own the collation to use <command>ALTER COLLATION</>. + You must own the collation to use <command>ALTER COLLATION</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the collation's schema. (These restrictions enforce that altering the diff --git a/doc/src/sgml/ref/alter_conversion.sgml b/doc/src/sgml/ref/alter_conversion.sgml index 3514720d03e..83fcbbd5a5d 100644 --- a/doc/src/sgml/ref/alter_conversion.sgml +++ b/doc/src/sgml/ref/alter_conversion.sgml @@ -36,7 +36,7 @@ ALTER CONVERSION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sch </para> <para> - You must own the conversion to use <command>ALTER CONVERSION</>. + You must own the conversion to use <command>ALTER CONVERSION</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the conversion's schema. (These restrictions enforce that altering the diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml index 59639d37291..35e4123cadd 100644 --- a/doc/src/sgml/ref/alter_database.sgml +++ b/doc/src/sgml/ref/alter_database.sgml @@ -89,7 +89,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL 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 <filename>postgresql.conf</> or has been received from the + in <filename>postgresql.conf</filename> or has been received from the <command>postgres</command> 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 @@ -183,7 +183,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL database-specific setting is removed, so the system-wide default setting will be inherited in new sessions. Use <literal>RESET ALL</literal> to clear all database-specific settings. - <literal>SET FROM CURRENT</> saves the session's current value of + <literal>SET FROM CURRENT</literal> saves the session's current value of the parameter as the database-specific value. </para> diff --git a/doc/src/sgml/ref/alter_default_privileges.sgml b/doc/src/sgml/ref/alter_default_privileges.sgml index 09eabda68ac..6c34f2446a7 100644 --- a/doc/src/sgml/ref/alter_default_privileges.sgml +++ b/doc/src/sgml/ref/alter_default_privileges.sgml @@ -88,7 +88,7 @@ REVOKE [ GRANT OPTION FOR ] <title>Description</title> <para> - <command>ALTER DEFAULT PRIVILEGES</> allows you to set the privileges + <command>ALTER DEFAULT PRIVILEGES</command> 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 @@ -109,9 +109,9 @@ REVOKE [ GRANT OPTION FOR ] As explained under <xref linkend="sql-grant">, the default privileges for any object type normally grant all grantable permissions to the object owner, and may grant some privileges to - <literal>PUBLIC</> as well. However, this behavior can be changed by + <literal>PUBLIC</literal> as well. However, this behavior can be changed by altering the global default privileges with - <command>ALTER DEFAULT PRIVILEGES</>. + <command>ALTER DEFAULT PRIVILEGES</command>. </para> <refsect2> @@ -123,7 +123,7 @@ REVOKE [ GRANT OPTION FOR ] <listitem> <para> The name of an existing role of which the current role is a member. - If <literal>FOR ROLE</> is omitted, the current role is assumed. + If <literal>FOR ROLE</literal> is omitted, the current role is assumed. </para> </listitem> </varlistentry> @@ -134,9 +134,9 @@ REVOKE [ GRANT OPTION FOR ] <para> The name of an existing schema. If specified, the default privileges are altered for objects later created in that schema. - If <literal>IN SCHEMA</> is omitted, the global default privileges + If <literal>IN SCHEMA</literal> is omitted, the global default privileges are altered. - <literal>IN SCHEMA</> is not allowed when using <literal>ON SCHEMAS</> + <literal>IN SCHEMA</literal> is not allowed when using <literal>ON SCHEMAS</literal> as schemas can't be nested. </para> </listitem> @@ -148,7 +148,7 @@ REVOKE [ GRANT OPTION FOR ] <para> The name of an existing role to grant or revoke privileges for. This parameter, and all the other parameters in - <replaceable class="parameter">abbreviated_grant_or_revoke</>, + <replaceable class="parameter">abbreviated_grant_or_revoke</replaceable>, act as described under <xref linkend="sql-grant"> or <xref linkend="sql-revoke">, @@ -175,7 +175,7 @@ REVOKE [ GRANT OPTION FOR ] <para> 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 <command>DROP OWNED BY</> to get rid of the default privileges entry + or use <command>DROP OWNED BY</command> to get rid of the default privileges entry for the role. </para> </refsect1> @@ -186,7 +186,7 @@ REVOKE [ GRANT OPTION FOR ] <para> Grant SELECT privilege to everyone for all tables (and views) you subsequently create in schema <literal>myschema</literal>, and allow - role <literal>webuser</> to INSERT into them too: + role <literal>webuser</literal> to INSERT into them too: <programlisting> ALTER DEFAULT PRIVILEGES IN SCHEMA myschema GRANT SELECT ON TABLES TO PUBLIC; @@ -206,7 +206,7 @@ ALTER DEFAULT PRIVILEGES IN SCHEMA myschema REVOKE INSERT ON TABLES FROM webuser <para> Remove the public EXECUTE permission that is normally granted on functions, - for all functions subsequently created by role <literal>admin</>: + for all functions subsequently created by role <literal>admin</literal>: <programlisting> ALTER DEFAULT PRIVILEGES FOR ROLE admin REVOKE EXECUTE ON FUNCTIONS FROM PUBLIC; diff --git a/doc/src/sgml/ref/alter_domain.sgml b/doc/src/sgml/ref/alter_domain.sgml index 827a1c7d20e..96a7db95ecf 100644 --- a/doc/src/sgml/ref/alter_domain.sgml +++ b/doc/src/sgml/ref/alter_domain.sgml @@ -69,7 +69,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> <listitem> <para> These forms change whether a domain is marked to allow NULL - values or to reject NULL values. You can only <literal>SET NOT NULL</> + values or to reject NULL values. You can only <literal>SET NOT NULL</literal> when the columns using the domain contain no null values. </para> </listitem> @@ -88,7 +88,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> valid using <command>ALTER DOMAIN ... VALIDATE CONSTRAINT</command>. Newly inserted or updated rows are always checked against all constraints, even those marked <literal>NOT VALID</literal>. - <literal>NOT VALID</> is only accepted for <literal>CHECK</> constraints. + <literal>NOT VALID</literal> is only accepted for <literal>CHECK</literal> constraints. </para> </listitem> </varlistentry> @@ -118,7 +118,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> <listitem> <para> This form validates a constraint previously added as - <literal>NOT VALID</>, that is, verify that all data in columns using the + <literal>NOT VALID</literal>, that is, verify that all data in columns using the domain satisfy the specified constraint. </para> </listitem> @@ -154,7 +154,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> </variablelist> <para> - You must own the domain to use <command>ALTER DOMAIN</>. + You must own the domain to use <command>ALTER DOMAIN</command>. To change the schema of a domain, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -273,8 +273,8 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - Currently, <command>ALTER DOMAIN ADD CONSTRAINT</>, <command>ALTER - DOMAIN VALIDATE CONSTRAINT</>, and <command>ALTER DOMAIN SET NOT NULL</> + Currently, <command>ALTER DOMAIN ADD CONSTRAINT</command>, <command>ALTER + DOMAIN VALIDATE CONSTRAINT</command>, and <command>ALTER DOMAIN SET NOT NULL</command> will fail if the validated named domain or any derived domain is used within a composite-type column of any table in the database. They should eventually be improved to be @@ -330,10 +330,10 @@ ALTER DOMAIN zipcode SET SCHEMA customers; <para> <command>ALTER DOMAIN</command> conforms to the <acronym>SQL</acronym> - standard, except for the <literal>OWNER</>, <literal>RENAME</literal>, <literal>SET SCHEMA</>, and - <literal>VALIDATE CONSTRAINT</> variants, which are - <productname>PostgreSQL</productname> extensions. The <literal>NOT VALID</> - clause of the <literal>ADD CONSTRAINT</> variant is also a + standard, except for the <literal>OWNER</literal>, <literal>RENAME</literal>, <literal>SET SCHEMA</literal>, and + <literal>VALIDATE CONSTRAINT</literal> variants, which are + <productname>PostgreSQL</productname> extensions. The <literal>NOT VALID</literal> + clause of the <literal>ADD CONSTRAINT</literal> variant is also a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_extension.sgml b/doc/src/sgml/ref/alter_extension.sgml index ae84e98e49a..c6c831fa30a 100644 --- a/doc/src/sgml/ref/alter_extension.sgml +++ b/doc/src/sgml/ref/alter_extension.sgml @@ -89,7 +89,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <listitem> <para> This form moves the extension's objects into another schema. The - extension has to be <firstterm>relocatable</> for this command to + extension has to be <firstterm>relocatable</firstterm> for this command to succeed. </para> </listitem> @@ -125,7 +125,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <para> You must own the extension to use <command>ALTER EXTENSION</command>. - The <literal>ADD</>/<literal>DROP</> forms require ownership of the + The <literal>ADD</literal>/<literal>DROP</literal> forms require ownership of the added/dropped object as well. </para> </refsect1> @@ -150,7 +150,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <para> The desired new version of the extension. This can be written as either an identifier or a string literal. If not specified, - <command>ALTER EXTENSION UPDATE</> attempts to update to whatever is + <command>ALTER EXTENSION UPDATE</command> attempts to update to whatever is shown as the default version in the extension's control file. </para> </listitem> @@ -205,14 +205,14 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <listitem> <para> The mode of a function or aggregate - argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>ALTER EXTENSION</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -246,7 +246,7 @@ ALTER EXTENSION <replaceable class="parameter">name</replaceable> DROP <replacea <listitem> <para> The data type(s) of the operator's arguments (optionally - schema-qualified). Write <literal>NONE</> for the missing argument + schema-qualified). Write <literal>NONE</literal> for the missing argument of a prefix or postfix operator. </para> </listitem> @@ -314,7 +314,7 @@ ALTER EXTENSION hstore ADD FUNCTION populate_record(anyelement, hstore); <title>Compatibility</title> <para> - <command>ALTER EXTENSION</command> is a <productname>PostgreSQL</> + <command>ALTER EXTENSION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml index 9c5b84fe64d..1c0a26de6ba 100644 --- a/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/alter_foreign_data_wrapper.sgml @@ -93,11 +93,11 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> REN <para> 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. <productname>PostgreSQL</> does + invalid according to the new validator. <productname>PostgreSQL</productname> 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 <command>ALTER FOREIGN DATA - WRAPPER</> command will be checked using the new validator. + WRAPPER</command> command will be checked using the new validator. </para> </listitem> </varlistentry> @@ -117,8 +117,8 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> REN <listitem> <para> Change options for the foreign-data - wrapper. <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + wrapper. <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Option names must be unique; names and values are also validated using the foreign data wrapper's validator function, if any. @@ -150,16 +150,16 @@ ALTER FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> REN <title>Examples</title> <para> - Change a foreign-data wrapper <literal>dbi</>, add - option <literal>foo</>, drop <literal>bar</>: + Change a foreign-data wrapper <literal>dbi</literal>, add + option <literal>foo</literal>, drop <literal>bar</literal>: <programlisting> ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP 'bar'); </programlisting> </para> <para> - Change the foreign-data wrapper <literal>dbi</> validator - to <literal>bob.myvalidator</>: + Change the foreign-data wrapper <literal>dbi</literal> validator + to <literal>bob.myvalidator</literal>: <programlisting> ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator; </programlisting></para> @@ -171,7 +171,7 @@ ALTER FOREIGN DATA WRAPPER dbi VALIDATOR bob.myvalidator; <para> <command>ALTER FOREIGN DATA WRAPPER</command> conforms to ISO/IEC 9075-9 (SQL/MED), except that the <literal>HANDLER</literal>, - <literal>VALIDATOR</>, <literal>OWNER TO</>, and <literal>RENAME</literal> + <literal>VALIDATOR</literal>, <literal>OWNER TO</literal>, and <literal>RENAME</literal> clauses are extensions. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_foreign_table.sgml b/doc/src/sgml/ref/alter_foreign_table.sgml index cb4e7044fbd..44d981a5bda 100644 --- a/doc/src/sgml/ref/alter_foreign_table.sgml +++ b/doc/src/sgml/ref/alter_foreign_table.sgml @@ -85,7 +85,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <listitem> <para> This form drops a column from a foreign table. - You will need to say <literal>CASCADE</> if + You will need to say <literal>CASCADE</literal> if anything outside the table depends on the column; for example, views. If <literal>IF EXISTS</literal> is specified and the column @@ -101,7 +101,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> 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 <productname>PostgreSQL</> believes the column to + changes the type that <productname>PostgreSQL</productname> believes the column to have. </para> </listitem> @@ -113,7 +113,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> These forms set or remove the default value for a column. Default values only apply in subsequent <command>INSERT</command> - or <command>UPDATE</> commands; they do not cause rows already in the + or <command>UPDATE</command> commands; they do not cause rows already in the table to change. </para> </listitem> @@ -174,7 +174,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> This form adds a new constraint to a foreign table, using the same syntax as <xref linkend="SQL-CREATEFOREIGNTABLE">. - Currently only <literal>CHECK</> constraints are supported. + Currently only <literal>CHECK</literal> constraints are supported. </para> <para> @@ -183,7 +183,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab declares that some new condition should be assumed to hold for all rows in the foreign table. (See the discussion in <xref linkend="SQL-CREATEFOREIGNTABLE">.) - If the constraint is marked <literal>NOT VALID</>, then it isn't + If the constraint is marked <literal>NOT VALID</literal>, then it isn't assumed to hold, but is only recorded for possible future use. </para> </listitem> @@ -235,9 +235,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab </para> <para> - Note that this is not equivalent to <literal>ADD COLUMN oid oid</>; + Note that this is not equivalent to <literal>ADD COLUMN oid oid</literal>; that would add a normal column that happened to be named - <literal>oid</>, not a system column. + <literal>oid</literal>, not a system column. </para> </listitem> </varlistentry> @@ -292,8 +292,8 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <listitem> <para> Change options for the foreign table or one of its columns. - <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Duplicate option names are not allowed (although it's OK for a table option and a column option to have the same name). Option names and values are also validated using the @@ -325,7 +325,7 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab </para> <para> - All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</> + All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</literal> 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 @@ -333,13 +333,13 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab </para> <para> - If the command is written as <literal>ALTER FOREIGN TABLE IF EXISTS ...</> + If the command is written as <literal>ALTER FOREIGN TABLE IF EXISTS ...</literal> and the foreign table does not exist, no error is thrown. A notice is issued in this case. </para> <para> - You must own the table to use <command>ALTER FOREIGN TABLE</>. + You must own the table to use <command>ALTER FOREIGN TABLE</command>. To change the schema of a foreign table, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -362,10 +362,10 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <listitem> <para> The name (possibly schema-qualified) of an existing foreign table to - alter. If <literal>ONLY</> is specified before the table name, only - that table is altered. If <literal>ONLY</> is not specified, the table + alter. If <literal>ONLY</literal> is specified before the table name, only + that table is altered. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are altered. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -518,9 +518,9 @@ ALTER FOREIGN TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceab <para> Consistency with the foreign server is not checked when a column is added or removed with <literal>ADD COLUMN</literal> or - <literal>DROP COLUMN</literal>, a <literal>NOT NULL</> - or <literal>CHECK</> constraint is added, or a column type is changed - with <literal>SET DATA TYPE</>. It is the user's responsibility to ensure + <literal>DROP COLUMN</literal>, a <literal>NOT NULL</literal> + or <literal>CHECK</literal> constraint is added, or a column type is changed + with <literal>SET DATA TYPE</literal>. It is the user's responsibility to ensure that the table definition matches the remote side. </para> @@ -552,16 +552,16 @@ ALTER FOREIGN TABLE myschema.distributors OPTIONS (ADD opt1 'value', SET opt2 'v <title>Compatibility</title> <para> - The forms <literal>ADD</literal>, <literal>DROP</>, + The forms <literal>ADD</literal>, <literal>DROP</literal>, and <literal>SET DATA TYPE</literal> conform with the SQL standard. The other forms are <productname>PostgreSQL</productname> extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single - <command>ALTER FOREIGN TABLE</> command is an extension. + <command>ALTER FOREIGN TABLE</command> command is an extension. </para> <para> - <command>ALTER FOREIGN TABLE DROP COLUMN</> can be used to drop the only + <command>ALTER FOREIGN TABLE DROP COLUMN</command> 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. </para> diff --git a/doc/src/sgml/ref/alter_function.sgml b/doc/src/sgml/ref/alter_function.sgml index 8d9fec6005a..cdecf631b1e 100644 --- a/doc/src/sgml/ref/alter_function.sgml +++ b/doc/src/sgml/ref/alter_function.sgml @@ -56,8 +56,8 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param </para> <para> - You must own the function to use <command>ALTER FUNCTION</>. - To change a function's schema, you must also have <literal>CREATE</> + You must own the function to use <command>ALTER FUNCTION</command>. + To change a function's schema, you must also have <literal>CREATE</literal> 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 <literal>CREATE</literal> privilege on @@ -86,14 +86,14 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param <listitem> <para> - The mode of an argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>ALTER FUNCTION</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -260,8 +260,8 @@ ALTER FUNCTION <replaceable>name</replaceable> [ ( [ [ <replaceable class="param setting is removed, so that the function executes with the value present in its environment. Use <literal>RESET ALL</literal> to clear all function-local settings. - <literal>SET FROM CURRENT</> saves the value of the parameter that - is current when <command>ALTER FUNCTION</> is executed as the value + <literal>SET FROM CURRENT</literal> saves the value of the parameter that + is current when <command>ALTER FUNCTION</command> is executed as the value to be applied when the function is entered. </para> @@ -329,7 +329,7 @@ ALTER FUNCTION check_password(text) SET search_path = admin, pg_temp; </para> <para> - To disable automatic setting of <varname>search_path</> for a function: + To disable automatic setting of <varname>search_path</varname> for a function: <programlisting> ALTER FUNCTION check_password(text) RESET search_path; </programlisting> @@ -343,13 +343,13 @@ ALTER FUNCTION check_password(text) RESET search_path; <para> This statement is partially compatible with the <command>ALTER - FUNCTION</> statement in the SQL standard. The standard allows more + FUNCTION</command> 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 <literal>RESTRICT</> key word, which is optional in - <productname>PostgreSQL</>. + requires the <literal>RESTRICT</literal> key word, which is optional in + <productname>PostgreSQL</productname>. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_group.sgml b/doc/src/sgml/ref/alter_group.sgml index f7136c773a7..a9001458731 100644 --- a/doc/src/sgml/ref/alter_group.sgml +++ b/doc/src/sgml/ref/alter_group.sgml @@ -46,10 +46,10 @@ ALTER GROUP <replaceable class="parameter">group_name</replaceable> RENAME TO <r <para> The first two variants add users to a group or remove them from a group. - (Any role can play the part of either a <quote>user</> or a - <quote>group</> for this purpose.) These variants are effectively + (Any role can play the part of either a <quote>user</quote> or a + <quote>group</quote> for this purpose.) These variants are effectively equivalent to granting or revoking membership in the role named as the - <quote>group</>; so the preferred way to do this is to use + <quote>group</quote>; so the preferred way to do this is to use <xref linkend="SQL-GRANT"> or <xref linkend="SQL-REVOKE">. </para> @@ -79,7 +79,7 @@ ALTER GROUP <replaceable class="parameter">group_name</replaceable> RENAME TO <r <listitem> <para> Users (roles) that are to be added to or removed from the group. - The users must already exist; <command>ALTER GROUP</> does not + The users must already exist; <command>ALTER GROUP</command> does not create or drop users. </para> </listitem> diff --git a/doc/src/sgml/ref/alter_index.sgml b/doc/src/sgml/ref/alter_index.sgml index 4c777f86752..30e399e62c8 100644 --- a/doc/src/sgml/ref/alter_index.sgml +++ b/doc/src/sgml/ref/alter_index.sgml @@ -106,7 +106,7 @@ ALTER INDEX ALL IN TABLESPACE <replaceable class="parameter">name</replaceable> <listitem> <para> This form resets one or more index-method-specific storage parameters to - their defaults. As with <literal>SET</>, a <literal>REINDEX</literal> + their defaults. As with <literal>SET</literal>, a <literal>REINDEX</literal> might be needed to update the index entirely. </para> </listitem> @@ -226,12 +226,12 @@ ALTER INDEX ALL IN TABLESPACE <replaceable class="parameter">name</replaceable> <para> These operations are also possible using <xref linkend="SQL-ALTERTABLE">. - <command>ALTER INDEX</> is in fact just an alias for the forms - of <command>ALTER TABLE</> that apply to indexes. + <command>ALTER INDEX</command> is in fact just an alias for the forms + of <command>ALTER TABLE</command> that apply to indexes. </para> <para> - There was formerly an <command>ALTER INDEX OWNER</> variant, but + There was formerly an <command>ALTER INDEX OWNER</command> variant, but this is now ignored (with a warning). An index cannot have an owner different from its table's owner. Changing the table's owner automatically changes the index as well. @@ -280,7 +280,7 @@ ALTER INDEX coord_idx ALTER COLUMN 3 SET STATISTICS 1000; <title>Compatibility</title> <para> - <command>ALTER INDEX</> is a <productname>PostgreSQL</productname> + <command>ALTER INDEX</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_materialized_view.sgml b/doc/src/sgml/ref/alter_materialized_view.sgml index a1cced1581c..eaea819744a 100644 --- a/doc/src/sgml/ref/alter_materialized_view.sgml +++ b/doc/src/sgml/ref/alter_materialized_view.sgml @@ -58,8 +58,8 @@ ALTER MATERIALIZED VIEW ALL IN TABLESPACE <replaceable class="parameter">name</r <para> You must own the materialized view to use <command>ALTER MATERIALIZED - VIEW</>. To change a materialized view's schema, you must also have - <literal>CREATE</> privilege on the new schema. + VIEW</command>. To change a materialized view's schema, you must also have + <literal>CREATE</literal> 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 <literal>CREATE</literal> privilege on the materialized view's schema. (These restrictions enforce that altering diff --git a/doc/src/sgml/ref/alter_opclass.sgml b/doc/src/sgml/ref/alter_opclass.sgml index 58de603aa46..834f3e4231d 100644 --- a/doc/src/sgml/ref/alter_opclass.sgml +++ b/doc/src/sgml/ref/alter_opclass.sgml @@ -41,7 +41,7 @@ ALTER OPERATOR CLASS <replaceable>name</replaceable> USING <replaceable class="p </para> <para> - You must own the operator class to use <command>ALTER OPERATOR CLASS</>. + You must own the operator class to use <command>ALTER OPERATOR CLASS</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the operator class's schema. (These restrictions enforce that altering the diff --git a/doc/src/sgml/ref/alter_operator.sgml b/doc/src/sgml/ref/alter_operator.sgml index 9579d00b786..3cc28d5b18a 100644 --- a/doc/src/sgml/ref/alter_operator.sgml +++ b/doc/src/sgml/ref/alter_operator.sgml @@ -43,7 +43,7 @@ ALTER OPERATOR <replaceable>name</replaceable> ( { <replaceable>left_type</repla </para> <para> - You must own the operator to use <command>ALTER OPERATOR</>. + You must own the operator to use <command>ALTER OPERATOR</command>. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have <literal>CREATE</literal> privilege on the operator's schema. (These restrictions enforce that altering the owner diff --git a/doc/src/sgml/ref/alter_opfamily.sgml b/doc/src/sgml/ref/alter_opfamily.sgml index 0bafe5b8f80..d15fbfceea8 100644 --- a/doc/src/sgml/ref/alter_opfamily.sgml +++ b/doc/src/sgml/ref/alter_opfamily.sgml @@ -57,7 +57,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <para> When operators and support functions are added to a family with <command>ALTER OPERATOR FAMILY</command>, they are not part of any - specific operator class within the family, but are just <quote>loose</> + specific operator class within the family, but are just <quote>loose</quote> within the family. This indicates that these operators and functions are compatible with the family's semantics, but are not required for correct functioning of any specific index. (Operators and functions @@ -74,7 +74,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - You must be a superuser to use <command>ALTER OPERATOR FAMILY</>. + You must be a superuser to use <command>ALTER OPERATOR FAMILY</command>. (This restriction is made because an erroneous operator family definition could confuse or even crash the server.) </para> @@ -139,15 +139,15 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <term><replaceable class="parameter">op_type</replaceable></term> <listitem> <para> - In an <literal>OPERATOR</> clause, - the operand data type(s) of the operator, or <literal>NONE</> to + In an <literal>OPERATOR</literal> clause, + the operand data type(s) of the operator, or <literal>NONE</literal> to signify a left-unary or right-unary operator. Unlike the comparable - syntax in <command>CREATE OPERATOR CLASS</>, the operand data types + syntax in <command>CREATE OPERATOR CLASS</command>, the operand data types must always be specified. </para> <para> - In an <literal>ADD FUNCTION</> clause, the operand data type(s) the + In an <literal>ADD FUNCTION</literal> 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 <replaceable @@ -159,7 +159,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - In a <literal>DROP FUNCTION</> clause, the operand data type(s) the + In a <literal>DROP FUNCTION</literal> clause, the operand data type(s) the function is intended to support must be specified. </para> </listitem> @@ -175,8 +175,8 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - If neither <literal>FOR SEARCH</> nor <literal>FOR ORDER BY</> is - specified, <literal>FOR SEARCH</> is the default. + If neither <literal>FOR SEARCH</literal> nor <literal>FOR ORDER BY</literal> is + specified, <literal>FOR SEARCH</literal> is the default. </para> </listitem> </varlistentry> @@ -240,7 +240,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </variablelist> <para> - The <literal>OPERATOR</> and <literal>FUNCTION</> + The <literal>OPERATOR</literal> and <literal>FUNCTION</literal> clauses can appear in any order. </para> @@ -250,10 +250,10 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <title>Notes</title> <para> - Notice that the <literal>DROP</> syntax only specifies the <quote>slot</> + Notice that the <literal>DROP</literal> syntax only specifies the <quote>slot</quote> 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 <literal>DROP FUNCTION</> the type(s) to specify + mentioned. Also, for <literal>DROP FUNCTION</literal> 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. @@ -274,9 +274,9 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" </para> <para> - Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</> - clause could include a <literal>RECHECK</> option. This is no longer - supported because whether an index operator is <quote>lossy</> is now + Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</literal> + clause could include a <literal>RECHECK</literal> option. This is no longer + supported because whether an index operator is <quote>lossy</quote> is now determined on-the-fly at run time. This allows efficient handling of cases where an operator might or might not be lossy. </para> @@ -288,7 +288,7 @@ ALTER OPERATOR FAMILY <replaceable>name</replaceable> USING <replaceable class=" <para> 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 <type>int4</> and <type>int2</>. + operator classes for data types <type>int4</type> and <type>int2</type>. </para> <programlisting> diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml index 7392e6f3de2..801404e0cf9 100644 --- a/doc/src/sgml/ref/alter_publication.sgml +++ b/doc/src/sgml/ref/alter_publication.sgml @@ -87,10 +87,10 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r <term><replaceable class="parameter">table_name</replaceable></term> <listitem> <para> - Name of an existing table. If <literal>ONLY</> is specified before the - table name, only that table is affected. If <literal>ONLY</> is not + Name of an existing table. If <literal>ONLY</literal> is specified before the + table name, only that table is affected. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are - affected. Optionally, <literal>*</> can be specified after the table + affected. Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -147,7 +147,7 @@ ALTER PUBLICATION mypublication ADD TABLE users, departments; <title>Compatibility</title> <para> - <command>ALTER PUBLICATION</command> is a <productname>PostgreSQL</> + <command>ALTER PUBLICATION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_role.sgml b/doc/src/sgml/ref/alter_role.sgml index 607b25962f0..e30ca104549 100644 --- a/doc/src/sgml/ref/alter_role.sgml +++ b/doc/src/sgml/ref/alter_role.sgml @@ -69,7 +69,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <xref linkend="SQL-REVOKE"> 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 <literal>CREATEROLE</> privilege can change any of these + Roles having <literal>CREATEROLE</literal> privilege can change any of these settings, but only for non-superuser and non-replication roles. Ordinary roles can only change their own password. </para> @@ -77,13 +77,13 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <para> The second variant changes the name of the role. Database superusers can rename any role. - Roles having <literal>CREATEROLE</> privilege can rename non-superuser + Roles having <literal>CREATEROLE</literal> 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 <literal>MD5</>-encrypted passwords use the role name as + Because <literal>MD5</literal>-encrypted passwords use the role name as cryptographic salt, renaming a role clears its password if the - password is <literal>MD5</>-encrypted. + password is <literal>MD5</literal>-encrypted. </para> <para> @@ -100,7 +100,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A Whenever the role subsequently starts a new session, the specified value becomes the session default, overriding whatever setting is present in - <filename>postgresql.conf</> or has been received from the <command>postgres</command> + <filename>postgresql.conf</filename> or has been received from the <command>postgres</command> command line. This only happens at login time; executing <xref linkend="sql-set-role"> or <xref linkend="sql-set-session-authorization"> does not cause new @@ -112,7 +112,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <para> Superusers can change anyone's session defaults. Roles having - <literal>CREATEROLE</> privilege can change defaults for non-superuser + <literal>CREATEROLE</literal> 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 @@ -155,8 +155,8 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <varlistentry> <term><literal>SUPERUSER</literal></term> <term><literal>NOSUPERUSER</literal></term> - <term><literal>CREATEDB</></term> - <term><literal>NOCREATEDB</></term> + <term><literal>CREATEDB</literal></term> + <term><literal>NOCREATEDB</literal></term> <term><literal>CREATEROLE</literal></term> <term><literal>NOCREATEROLE</literal></term> <term><literal>INHERIT</literal></term> @@ -168,7 +168,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A <term><literal>BYPASSRLS</literal></term> <term><literal>NOBYPASSRLS</literal></term> <term><literal>CONNECTION LIMIT</literal> <replaceable class="parameter">connlimit</replaceable></term> - <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> + <term>[ <literal>ENCRYPTED</literal> ] <literal>PASSWORD</literal> <replaceable class="parameter">password</replaceable></term> <term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term> <listitem> <para> @@ -209,7 +209,7 @@ ALTER ROLE { <replaceable class="parameter">role_specification</replaceable> | A role-specific variable setting is removed, so the role will inherit the system-wide default setting in new sessions. Use <literal>RESET ALL</literal> to clear all role-specific settings. - <literal>SET FROM CURRENT</> saves the session's current value of + <literal>SET FROM CURRENT</literal> saves the session's current value of the parameter as the role-specific value. If <literal>IN DATABASE</literal> is specified, the configuration parameter is set or removed for the given role and database only. @@ -288,7 +288,7 @@ ALTER ROLE davide WITH PASSWORD NULL; <para> 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 <acronym>UTC</>: + the time zone which is one hour ahead of <acronym>UTC</acronym>: <programlisting> ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1'; </programlisting> diff --git a/doc/src/sgml/ref/alter_schema.sgml b/doc/src/sgml/ref/alter_schema.sgml index dbc5c2d45f5..2ca406b9148 100644 --- a/doc/src/sgml/ref/alter_schema.sgml +++ b/doc/src/sgml/ref/alter_schema.sgml @@ -34,7 +34,7 @@ ALTER SCHEMA <replaceable>name</replaceable> OWNER TO { <replaceable>new_owner</ </para> <para> - You must own the schema to use <command>ALTER SCHEMA</>. + You must own the schema to use <command>ALTER SCHEMA</command>. To rename a schema you must also have the <literal>CREATE</literal> privilege for the database. To alter the owner, you must also be a direct or diff --git a/doc/src/sgml/ref/alter_sequence.sgml b/doc/src/sgml/ref/alter_sequence.sgml index c505935fcc2..9b8ad365227 100644 --- a/doc/src/sgml/ref/alter_sequence.sgml +++ b/doc/src/sgml/ref/alter_sequence.sgml @@ -47,8 +47,8 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S </para> <para> - You must own the sequence to use <command>ALTER SEQUENCE</>. - To change a sequence's schema, you must also have <literal>CREATE</> + You must own the sequence to use <command>ALTER SEQUENCE</command>. + To change a sequence's schema, you must also have <literal>CREATE</literal> 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 <literal>CREATE</literal> privilege on @@ -159,8 +159,8 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S The optional clause <literal>START WITH <replaceable class="parameter">start</replaceable></literal> changes the recorded start value of the sequence. This has no effect on the - <emphasis>current</> sequence value; it simply sets the value - that future <command>ALTER SEQUENCE RESTART</> commands will use. + <emphasis>current</emphasis> sequence value; it simply sets the value + that future <command>ALTER SEQUENCE RESTART</command> commands will use. </para> </listitem> </varlistentry> @@ -172,13 +172,13 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S The optional clause <literal>RESTART [ WITH <replaceable class="parameter">restart</replaceable> ]</literal> changes the current value of the sequence. This is similar to calling the - <function>setval</> function with <literal>is_called</literal> = - <literal>false</>: the specified value will be returned by the - <emphasis>next</> call of <function>nextval</>. - Writing <literal>RESTART</> with no <replaceable - class="parameter">restart</> value is equivalent to supplying - the start value that was recorded by <command>CREATE SEQUENCE</> - or last set by <command>ALTER SEQUENCE START WITH</>. + <function>setval</function> function with <literal>is_called</literal> = + <literal>false</literal>: the specified value will be returned by the + <emphasis>next</emphasis> call of <function>nextval</function>. + Writing <literal>RESTART</literal> with no <replaceable + class="parameter">restart</replaceable> value is equivalent to supplying + the start value that was recorded by <command>CREATE SEQUENCE</command> + or last set by <command>ALTER SEQUENCE START WITH</command>. </para> <para> @@ -186,7 +186,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S a <literal>RESTART</literal> operation on a sequence is transactional and blocks concurrent transactions from obtaining numbers from the same sequence. If that's not the desired mode of - operation, <function>setval</> should be used. + operation, <function>setval</function> should be used. </para> </listitem> </varlistentry> @@ -250,7 +250,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S table must have the same owner and be in the same schema as the sequence. Specifying <literal>OWNED BY NONE</literal> removes any existing - association, making the sequence <quote>free-standing</>. + association, making the sequence <quote>free-standing</quote>. </para> </listitem> </varlistentry> @@ -291,7 +291,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S <para> <command>ALTER SEQUENCE</command> will not immediately affect - <function>nextval</> results in backends, + <function>nextval</function> 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 @@ -299,7 +299,7 @@ ALTER SEQUENCE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> S </para> <para> - <command>ALTER SEQUENCE</command> does not affect the <function>currval</> + <command>ALTER SEQUENCE</command> does not affect the <function>currval</function> status for the sequence. (Before <productname>PostgreSQL</productname> 8.3, it sometimes did.) </para> @@ -332,8 +332,8 @@ ALTER SEQUENCE serial RESTART WITH 105; <para> <command>ALTER SEQUENCE</command> conforms to the <acronym>SQL</acronym> - standard, except for the <literal>AS</literal>, <literal>START WITH</>, - <literal>OWNED BY</>, <literal>OWNER TO</>, <literal>RENAME TO</>, and + standard, except for the <literal>AS</literal>, <literal>START WITH</literal>, + <literal>OWNED BY</literal>, <literal>OWNER TO</literal>, <literal>RENAME TO</literal>, and <literal>SET SCHEMA</literal> clauses, which are <productname>PostgreSQL</productname> extensions. </para> diff --git a/doc/src/sgml/ref/alter_server.sgml b/doc/src/sgml/ref/alter_server.sgml index 7f5def30a40..05e11f5ef28 100644 --- a/doc/src/sgml/ref/alter_server.sgml +++ b/doc/src/sgml/ref/alter_server.sgml @@ -42,7 +42,7 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac 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 <literal>USAGE</> privilege on the server's foreign-data + have <literal>USAGE</literal> privilege on the server's foreign-data wrapper. (Note that superusers satisfy all these criteria automatically.) </para> @@ -75,8 +75,8 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac <listitem> <para> Change options for the - server. <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + server. <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Option names must be unique; names and values are also validated using the server's foreign-data wrapper library. @@ -108,15 +108,15 @@ ALTER SERVER <replaceable class="parameter">name</replaceable> RENAME TO <replac <title>Examples</title> <para> - Alter server <literal>foo</>, add connection options: + Alter server <literal>foo</literal>, add connection options: <programlisting> ALTER SERVER foo OPTIONS (host 'foo', dbname 'foodb'); </programlisting> </para> <para> - Alter server <literal>foo</>, change version, - change <literal>host</> option: + Alter server <literal>foo</literal>, change version, + change <literal>host</literal> option: <programlisting> ALTER SERVER foo VERSION '8.4' OPTIONS (SET host 'baz'); </programlisting></para> diff --git a/doc/src/sgml/ref/alter_statistics.sgml b/doc/src/sgml/ref/alter_statistics.sgml index db4f2f0d523..87acb879b03 100644 --- a/doc/src/sgml/ref/alter_statistics.sgml +++ b/doc/src/sgml/ref/alter_statistics.sgml @@ -39,9 +39,9 @@ ALTER STATISTICS <replaceable class="parameter">name</replaceable> SET SCHEMA <r </para> <para> - You must own the statistics object to use <command>ALTER STATISTICS</>. + You must own the statistics object to use <command>ALTER STATISTICS</command>. To change a statistics object's schema, you must also - have <literal>CREATE</> privilege on the new schema. + have <literal>CREATE</literal> 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 <literal>CREATE</literal> privilege on the statistics object's schema. (These restrictions enforce that altering diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml index 44c0b350692..b76a21f6545 100644 --- a/doc/src/sgml/ref/alter_subscription.sgml +++ b/doc/src/sgml/ref/alter_subscription.sgml @@ -42,7 +42,7 @@ ALTER SUBSCRIPTION <replaceable class="parameter">name</replaceable> RENAME TO < </para> <para> - You must own the subscription to use <command>ALTER SUBSCRIPTION</>. + You must own the subscription to use <command>ALTER SUBSCRIPTION</command>. 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 @@ -211,7 +211,7 @@ ALTER SUBSCRIPTION mysub DISABLE; <title>Compatibility</title> <para> - <command>ALTER SUBSCRIPTION</command> is a <productname>PostgreSQL</> + <command>ALTER SUBSCRIPTION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml index e3a4af4041f..b8ef117b7d7 100644 --- a/doc/src/sgml/ref/alter_system.sgml +++ b/doc/src/sgml/ref/alter_system.sgml @@ -50,8 +50,8 @@ ALTER SYSTEM RESET ALL 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 <function>pg_reload_conf()</>, running <literal>pg_ctl reload</>, - or sending a <systemitem>SIGHUP</> signal to the main server process. + function <function>pg_reload_conf()</function>, running <literal>pg_ctl reload</literal>, + or sending a <systemitem>SIGHUP</systemitem> signal to the main server process. </para> <para> @@ -95,8 +95,8 @@ ALTER SYSTEM RESET ALL <para> This command can't be used to set <xref linkend="guc-data-directory">, - nor parameters that are not allowed in <filename>postgresql.conf</> - (e.g., <link linkend="runtime-config-preset">preset options</>). + nor parameters that are not allowed in <filename>postgresql.conf</filename> + (e.g., <link linkend="runtime-config-preset">preset options</link>). </para> <para> @@ -108,7 +108,7 @@ ALTER SYSTEM RESET ALL <title>Examples</title> <para> - Set the <literal>wal_level</>: + Set the <literal>wal_level</literal>: <programlisting> ALTER SYSTEM SET wal_level = replica; </programlisting> @@ -116,7 +116,7 @@ ALTER SYSTEM SET wal_level = replica; <para> Undo that, restoring whatever setting was effective - in <filename>postgresql.conf</>: + in <filename>postgresql.conf</filename>: <programlisting> ALTER SYSTEM RESET wal_level; </programlisting></para> diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml index 0559f80549d..68393d70b41 100644 --- a/doc/src/sgml/ref/alter_table.sgml +++ b/doc/src/sgml/ref/alter_table.sgml @@ -126,7 +126,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> 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 <literal>CASCADE</> if anything outside the table + You will need to say <literal>CASCADE</literal> if anything outside the table depends on the column, for example, foreign key references or views. If <literal>IF EXISTS</literal> is specified and the column does not exist, no error is thrown. In this case a notice @@ -162,7 +162,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> These forms set or remove the default value for a column. Default values only apply in subsequent <command>INSERT</command> - or <command>UPDATE</> commands; they do not cause rows already in the + or <command>UPDATE</command> commands; they do not cause rows already in the table to change. </para> </listitem> @@ -174,7 +174,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> These forms change whether a column is marked to allow null values or to reject null values. You can only use <literal>SET - NOT NULL</> when the column contains no null values. + NOT NULL</literal> when the column contains no null values. </para> <para> @@ -182,7 +182,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> on a column if it is marked <literal>NOT NULL</literal> in the parent table. To drop the <literal>NOT NULL</literal> constraint from all the partitions, perform <literal>DROP NOT NULL</literal> on the parent - table. Even if there is no <literal>NOT NULL</> constraint on the + table. Even if there is no <literal>NOT NULL</literal> 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. @@ -249,17 +249,17 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form sets or resets per-attribute options. Currently, the only - defined per-attribute options are <literal>n_distinct</> and - <literal>n_distinct_inherited</>, which override the + defined per-attribute options are <literal>n_distinct</literal> and + <literal>n_distinct_inherited</literal>, which override the number-of-distinct-values estimates made by subsequent <xref linkend="sql-analyze"> - operations. <literal>n_distinct</> affects the statistics for the table - itself, while <literal>n_distinct_inherited</> affects the statistics + operations. <literal>n_distinct</literal> affects the statistics for the table + itself, while <literal>n_distinct_inherited</literal> affects the statistics gathered for the table plus its inheritance children. When set to a - positive value, <command>ANALYZE</> will assume that the column contains + positive value, <command>ANALYZE</command> 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, <command>ANALYZE</> will assume that the number of + than or equal to -1, <command>ANALYZE</command> 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, @@ -290,7 +290,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form sets the storage mode for a column. This controls whether this - column is held inline or in a secondary <acronym>TOAST</> table, and + column is held inline or in a secondary <acronym>TOAST</acronym> table, and whether the data should be compressed or not. <literal>PLAIN</literal> must be used for fixed-length values such as <type>integer</type> and is @@ -302,7 +302,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> Use of <literal>EXTERNAL</literal> will make substring operations on very large <type>text</type> and <type>bytea</type> values run faster, at the penalty of increased storage space. Note that - <literal>SET STORAGE</> doesn't itself change anything in the table, + <literal>SET STORAGE</literal> doesn't itself change anything in the table, it just sets the strategy to be pursued during future table updates. See <xref linkend="storage-toast"> for more information. </para> @@ -335,7 +335,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <term><literal>ADD <replaceable class="parameter">table_constraint_using_index</replaceable></literal></term> <listitem> <para> - This form adds a new <literal>PRIMARY KEY</> or <literal>UNIQUE</> + This form adds a new <literal>PRIMARY KEY</literal> or <literal>UNIQUE</literal> constraint to a table based on an existing unique index. All the columns of the index will be included in the constraint. </para> @@ -344,14 +344,14 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> 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 <literal>ADD PRIMARY KEY</> or <literal>ADD UNIQUE</> + built by a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal> command. </para> <para> - If <literal>PRIMARY KEY</> is specified, and the index's columns are not - already marked <literal>NOT NULL</>, then this command will attempt to - do <literal>ALTER COLUMN SET NOT NULL</> against each such column. + If <literal>PRIMARY KEY</literal> is specified, and the index's columns are not + already marked <literal>NOT NULL</literal>, then this command will attempt to + do <literal>ALTER COLUMN SET NOT NULL</literal> 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. </para> @@ -363,9 +363,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> </para> <para> - After this command is executed, the index is <quote>owned</> by the + After this command is executed, the index is <quote>owned</quote> by the constraint, in the same way as if the index had been built by - a regular <literal>ADD PRIMARY KEY</> or <literal>ADD UNIQUE</> + a regular <literal>ADD PRIMARY KEY</literal> or <literal>ADD UNIQUE</literal> command. In particular, dropping the constraint will make the index disappear too. </para> @@ -375,7 +375,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> 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 - <command>CREATE INDEX CONCURRENTLY</>, and then install it as an + <command>CREATE INDEX CONCURRENTLY</command>, and then install it as an official constraint using this syntax. See the example below. </para> </note> @@ -447,9 +447,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> triggers are not executed. The trigger firing mechanism is also affected by the configuration variable <xref linkend="guc-session-replication-role">. Simply enabled - triggers will fire when the replication role is <quote>origin</> - (the default) or <quote>local</>. Triggers configured as <literal>ENABLE - REPLICA</literal> will only fire if the session is in <quote>replica</> + triggers will fire when the replication role is <quote>origin</quote> + (the default) or <quote>local</quote>. Triggers configured as <literal>ENABLE + REPLICA</literal> will only fire if the session is in <quote>replica</quote> mode, and triggers configured as <literal>ENABLE ALWAYS</literal> will fire regardless of the current replication mode. </para> @@ -542,9 +542,9 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> </para> <para> - Note that this is not equivalent to <literal>ADD COLUMN oid oid</>; + Note that this is not equivalent to <literal>ADD COLUMN oid oid</literal>; that would add a normal column that happened to be named - <literal>oid</>, not a system column. + <literal>oid</literal>, not a system column. </para> </listitem> </varlistentry> @@ -609,8 +609,8 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> 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 <link linkend="SQL-VACUUM">VACUUM - FULL</>, <xref linkend="SQL-CLUSTER"> or one of the forms - of <command>ALTER TABLE</> that forces a table rewrite. + FULL</link>, <xref linkend="SQL-CLUSTER"> or one of the forms + of <command>ALTER TABLE</command> 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. @@ -620,18 +620,18 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <literal>SHARE UPDATE EXCLUSIVE</literal> lock will be taken for fillfactor and autovacuum storage parameters, as well as the following planner related parameters: - <varname>effective_io_concurrency</>, <varname>parallel_workers</>, <varname>seq_page_cost</>, - <varname>random_page_cost</>, <varname>n_distinct</> and <varname>n_distinct_inherited</>. + <varname>effective_io_concurrency</varname>, <varname>parallel_workers</varname>, <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname>, <varname>n_distinct</varname> and <varname>n_distinct_inherited</varname>. </para> <note> <para> - While <command>CREATE TABLE</> allows <literal>OIDS</> to be specified + While <command>CREATE TABLE</command> allows <literal>OIDS</literal> to be specified in the <literal>WITH (<replaceable - class="parameter">storage_parameter</>)</literal> syntax, - <command>ALTER TABLE</> does not treat <literal>OIDS</> as a - storage parameter. Instead use the <literal>SET WITH OIDS</> - and <literal>SET WITHOUT OIDS</> forms to change OID status. + class="parameter">storage_parameter</replaceable>)</literal> syntax, + <command>ALTER TABLE</command> does not treat <literal>OIDS</literal> as a + storage parameter. Instead use the <literal>SET WITH OIDS</literal> + and <literal>SET WITHOUT OIDS</literal> forms to change OID status. </para> </note> </listitem> @@ -642,7 +642,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form resets one or more storage parameters to their - defaults. As with <literal>SET</>, a table rewrite might be + defaults. As with <literal>SET</literal>, a table rewrite might be needed to update the table entirely. </para> </listitem> @@ -693,11 +693,11 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> This form links the table to a composite type as though <command>CREATE - TABLE OF</> had formed it. The table's list of column names and types + TABLE OF</command> had formed it. The table's list of column names and types must precisely match that of the composite type; the presence of - an <literal>oid</> system column is permitted to differ. The table must + an <literal>oid</literal> system column is permitted to differ. The table must not inherit from any other table. These restrictions ensure - that <command>CREATE TABLE OF</> would permit an equivalent table + that <command>CREATE TABLE OF</command> would permit an equivalent table definition. </para> </listitem> @@ -728,13 +728,13 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> This form changes the information which is written to the write-ahead log to identify rows which are updated or deleted. This option has no effect - except when logical replication is in use. <literal>DEFAULT</> + except when logical replication is in use. <literal>DEFAULT</literal> (the default for non-system tables) records the - old values of the columns of the primary key, if any. <literal>USING INDEX</> + old values of the columns of the primary key, if any. <literal>USING INDEX</literal> records the old values of the columns covered by the named index, which must be unique, not partial, not deferrable, and include only columns marked - <literal>NOT NULL</>. <literal>FULL</> records the old values of all columns - in the row. <literal>NOTHING</> records no information about the old row. + <literal>NOT NULL</literal>. <literal>FULL</literal> records the old values of all columns + in the row. <literal>NOTHING</literal> records no information about the old row. (This is the default for system tables.) In all cases, no old values are logged unless at least one of the columns that would be logged differs between the old and new versions of the row. @@ -853,7 +853,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> </para> <para> - You must own the table to use <command>ALTER TABLE</>. + You must own the table to use <command>ALTER TABLE</command>. To change the schema or tablespace of a table, you must also have <literal>CREATE</literal> privilege on the new schema or tablespace. To add the table as a new child of a parent table, you must own the parent @@ -890,10 +890,10 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <listitem> <para> The name (optionally schema-qualified) of an existing table to - alter. If <literal>ONLY</> is specified before the table name, only - that table is altered. If <literal>ONLY</> is not specified, the table + alter. If <literal>ONLY</literal> is specified before the table name, only + that table is altered. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are altered. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -1106,28 +1106,28 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> When a column is added with <literal>ADD COLUMN</literal>, all existing rows in the table are initialized with the column's default value - (NULL if no <literal>DEFAULT</> clause is specified). - If there is no <literal>DEFAULT</> clause, this is merely a metadata + (NULL if no <literal>DEFAULT</literal> clause is specified). + If there is no <literal>DEFAULT</literal> clause, this is merely a metadata change and does not require any immediate update of the table's data; the added NULL values are supplied on readout, instead. </para> <para> - Adding a column with a <literal>DEFAULT</> clause or changing the type of + Adding a column with a <literal>DEFAULT</literal> clause 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 <literal>USING</> clause does not change the column + if the <literal>USING</literal> 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; but any indexes on the affected columns must still be rebuilt. Adding or - removing a system <literal>oid</> column also requires rewriting the entire + removing a system <literal>oid</literal> column also requires rewriting the entire table. 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. </para> <para> - Adding a <literal>CHECK</> or <literal>NOT NULL</> constraint requires + Adding a <literal>CHECK</literal> or <literal>NOT NULL</literal> constraint requires scanning the table to verify that existing rows meet the constraint, but does not require a table rewrite. </para> @@ -1139,7 +1139,7 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <para> The main reason for providing the option to specify multiple changes - in a single <command>ALTER TABLE</> is that multiple table scans or + in a single <command>ALTER TABLE</command> is that multiple table scans or rewrites can thereby be combined into a single pass over the table. </para> @@ -1151,37 +1151,37 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> 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. (These statements do - not apply when dropping the system <literal>oid</> column; that is done + not apply when dropping the system <literal>oid</literal> column; that is done with an immediate rewrite.) </para> <para> To force immediate reclamation of space occupied by a dropped column, - you can execute one of the forms of <command>ALTER TABLE</> that + you can execute one of the forms of <command>ALTER TABLE</command> that performs a rewrite of the whole table. This results in reconstructing each row with the dropped column replaced by a null value. </para> <para> - The rewriting forms of <command>ALTER TABLE</> are not MVCC-safe. + The rewriting forms of <command>ALTER TABLE</command> 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 <xref linkend="mvcc-caveats"> for more details. </para> <para> - The <literal>USING</literal> option of <literal>SET DATA TYPE</> can actually + The <literal>USING</literal> option of <literal>SET DATA TYPE</literal> 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 <literal>SET DATA TYPE</> + very general conversions to be done with the <literal>SET DATA TYPE</literal> syntax. Because of this flexibility, the <literal>USING</literal> expression is not applied to the column's 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, <literal>SET DATA TYPE</> might fail to convert the default even + new type, <literal>SET DATA TYPE</literal> might fail to convert the default even though a <literal>USING</literal> clause is supplied. In such cases, - drop the default with <literal>DROP DEFAULT</>, perform the <literal>ALTER - TYPE</>, and then use <literal>SET DEFAULT</> to add a suitable new + drop the default with <literal>DROP DEFAULT</literal>, perform the <literal>ALTER + TYPE</literal>, and then use <literal>SET DEFAULT</literal> to add a suitable new default. Similar considerations apply to indexes and constraints involving the column. </para> @@ -1216,11 +1216,11 @@ ALTER TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> The actions for identity columns (<literal>ADD GENERATED</literal>, <literal>SET</literal> etc., <literal>DROP IDENTITY</literal>), as well as the actions - <literal>TRIGGER</>, <literal>CLUSTER</>, <literal>OWNER</>, - and <literal>TABLESPACE</> never recurse to descendant tables; - that is, they always act as though <literal>ONLY</> were specified. - Adding a constraint recurses only for <literal>CHECK</> constraints - that are not marked <literal>NO INHERIT</>. + <literal>TRIGGER</literal>, <literal>CLUSTER</literal>, <literal>OWNER</literal>, + and <literal>TABLESPACE</literal> never recurse to descendant tables; + that is, they always act as though <literal>ONLY</literal> were specified. + Adding a constraint recurses only for <literal>CHECK</literal> constraints + that are not marked <literal>NO INHERIT</literal>. </para> <para> @@ -1434,17 +1434,17 @@ ALTER TABLE measurement <para> The forms <literal>ADD</literal> (without <literal>USING INDEX</literal>), - <literal>DROP [COLUMN]</>, <literal>DROP IDENTITY</literal>, <literal>RESTART</literal>, - <literal>SET DEFAULT</>, <literal>SET DATA TYPE</literal> (without <literal>USING</literal>), + <literal>DROP [COLUMN]</literal>, <literal>DROP IDENTITY</literal>, <literal>RESTART</literal>, + <literal>SET DEFAULT</literal>, <literal>SET DATA TYPE</literal> (without <literal>USING</literal>), <literal>SET GENERATED</literal>, and <literal>SET <replaceable>sequence_option</replaceable></literal> conform with the SQL standard. The other forms are <productname>PostgreSQL</productname> extensions of the SQL standard. Also, the ability to specify more than one manipulation in a single - <command>ALTER TABLE</> command is an extension. + <command>ALTER TABLE</command> command is an extension. </para> <para> - <command>ALTER TABLE DROP COLUMN</> can be used to drop the only + <command>ALTER TABLE DROP COLUMN</command> 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. </para> diff --git a/doc/src/sgml/ref/alter_tablespace.sgml b/doc/src/sgml/ref/alter_tablespace.sgml index 4542bd90a21..def554bfb33 100644 --- a/doc/src/sgml/ref/alter_tablespace.sgml +++ b/doc/src/sgml/ref/alter_tablespace.sgml @@ -83,8 +83,8 @@ ALTER TABLESPACE <replaceable>name</replaceable> RESET ( <replaceable class="par <listitem> <para> A tablespace parameter to be set or reset. Currently, the only - available parameters are <varname>seq_page_cost</>, - <varname>random_page_cost</> and <varname>effective_io_concurrency</>. + available parameters are <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname> and <varname>effective_io_concurrency</varname>. Setting either value for a particular tablespace will override the planner's usual estimate of the cost of reading pages from tables in that tablespace, as established by the configuration parameters of the diff --git a/doc/src/sgml/ref/alter_trigger.sgml b/doc/src/sgml/ref/alter_trigger.sgml index 3e48d159e27..2e872cf11f2 100644 --- a/doc/src/sgml/ref/alter_trigger.sgml +++ b/doc/src/sgml/ref/alter_trigger.sgml @@ -91,7 +91,7 @@ ALTER TRIGGER <replaceable class="parameter">name</replaceable> ON <replaceable <para> The ability to temporarily enable or disable a trigger is provided by <xref linkend="SQL-ALTERTABLE">, not by - <command>ALTER TRIGGER</>, because <command>ALTER TRIGGER</> has no + <command>ALTER TRIGGER</command>, because <command>ALTER TRIGGER</command> has no convenient way to express the option of enabling or disabling all of a table's triggers at once. </para> @@ -117,7 +117,7 @@ ALTER TRIGGER emp_stamp ON emp DEPENDS ON EXTENSION emplib; <title>Compatibility</title> <para> - <command>ALTER TRIGGER</command> is a <productname>PostgreSQL</> + <command>ALTER TRIGGER</command> is a <productname>PostgreSQL</productname> extension of the SQL standard. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_tsconfig.sgml b/doc/src/sgml/ref/alter_tsconfig.sgml index 72a719b8629..b44aac9bf58 100644 --- a/doc/src/sgml/ref/alter_tsconfig.sgml +++ b/doc/src/sgml/ref/alter_tsconfig.sgml @@ -49,7 +49,7 @@ ALTER TEXT SEARCH CONFIGURATION <replaceable>name</replaceable> SET SCHEMA <repl <para> You must be the owner of the configuration to use - <command>ALTER TEXT SEARCH CONFIGURATION</>. + <command>ALTER TEXT SEARCH CONFIGURATION</command>. </para> </refsect1> @@ -136,20 +136,20 @@ ALTER TEXT SEARCH CONFIGURATION <replaceable>name</replaceable> SET SCHEMA <repl </variablelist> <para> - The <literal>ADD MAPPING FOR</> form installs a list of dictionaries to be + The <literal>ADD MAPPING FOR</literal> 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 <literal>ALTER MAPPING FOR</> form does the same, but first removing + The <literal>ALTER MAPPING FOR</literal> form does the same, but first removing any existing mapping for those token types. - The <literal>ALTER MAPPING REPLACE</> forms substitute <replaceable + The <literal>ALTER MAPPING REPLACE</literal> forms substitute <replaceable class="parameter">new_dictionary</replaceable> for <replaceable class="parameter">old_dictionary</replaceable> anywhere the latter appears. - This is done for only the specified token types when <literal>FOR</> + This is done for only the specified token types when <literal>FOR</literal> appears, or for all mappings of the configuration when it doesn't. - The <literal>DROP MAPPING</> form removes all dictionaries for the + The <literal>DROP MAPPING</literal> 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 <literal>IF EXISTS</> appears. + for the token types, unless <literal>IF EXISTS</literal> appears. </para> </refsect1> @@ -158,9 +158,9 @@ ALTER TEXT SEARCH CONFIGURATION <replaceable>name</replaceable> SET SCHEMA <repl <title>Examples</title> <para> - The following example replaces the <literal>english</> dictionary - with the <literal>swedish</> dictionary anywhere that <literal>english</> - is used within <literal>my_config</>. + The following example replaces the <literal>english</literal> dictionary + with the <literal>swedish</literal> dictionary anywhere that <literal>english</literal> + is used within <literal>my_config</literal>. </para> <programlisting> diff --git a/doc/src/sgml/ref/alter_tsdictionary.sgml b/doc/src/sgml/ref/alter_tsdictionary.sgml index 7cecabea83b..16d76687ab1 100644 --- a/doc/src/sgml/ref/alter_tsdictionary.sgml +++ b/doc/src/sgml/ref/alter_tsdictionary.sgml @@ -41,7 +41,7 @@ ALTER TEXT SEARCH DICTIONARY <replaceable>name</replaceable> SET SCHEMA <replace <para> You must be the owner of the dictionary to use - <command>ALTER TEXT SEARCH DICTIONARY</>. + <command>ALTER TEXT SEARCH DICTIONARY</command>. </para> </refsect1> @@ -126,7 +126,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( StopWords = newrussian ); </programlisting> <para> - The following example command changes the language option to <literal>dutch</>, + The following example command changes the language option to <literal>dutch</literal>, and removes the stopword option entirely. </para> @@ -135,7 +135,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( language = dutch, StopWords ); </programlisting> <para> - The following example command <quote>updates</> the dictionary's + The following example command <quote>updates</quote> the dictionary's definition without actually changing anything. <programlisting> @@ -144,7 +144,7 @@ ALTER TEXT SEARCH DICTIONARY my_dict ( dummy ); (The reason this works is that the option removal code doesn't complain if there is no such option.) This trick is useful when changing - configuration files for the dictionary: the <command>ALTER</> will + configuration files for the dictionary: the <command>ALTER</command> will force existing database sessions to re-read the configuration files, which otherwise they would never do if they had read them earlier. </para> diff --git a/doc/src/sgml/ref/alter_tsparser.sgml b/doc/src/sgml/ref/alter_tsparser.sgml index e2b6060a17a..737a5075657 100644 --- a/doc/src/sgml/ref/alter_tsparser.sgml +++ b/doc/src/sgml/ref/alter_tsparser.sgml @@ -36,7 +36,7 @@ ALTER TEXT SEARCH PARSER <replaceable>name</replaceable> SET SCHEMA <replaceable </para> <para> - You must be a superuser to use <command>ALTER TEXT SEARCH PARSER</>. + You must be a superuser to use <command>ALTER TEXT SEARCH PARSER</command>. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_tstemplate.sgml b/doc/src/sgml/ref/alter_tstemplate.sgml index e7ae91c0a08..d9a753017b5 100644 --- a/doc/src/sgml/ref/alter_tstemplate.sgml +++ b/doc/src/sgml/ref/alter_tstemplate.sgml @@ -36,7 +36,7 @@ ALTER TEXT SEARCH TEMPLATE <replaceable>name</replaceable> SET SCHEMA <replaceab </para> <para> - You must be a superuser to use <command>ALTER TEXT SEARCH TEMPLATE</>. + You must be a superuser to use <command>ALTER TEXT SEARCH TEMPLATE</command>. </para> </refsect1> diff --git a/doc/src/sgml/ref/alter_type.sgml b/doc/src/sgml/ref/alter_type.sgml index 6c5201ccb59..75be3187f14 100644 --- a/doc/src/sgml/ref/alter_type.sgml +++ b/doc/src/sgml/ref/alter_type.sgml @@ -147,7 +147,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla </para> <para> - You must own the type to use <command>ALTER TYPE</>. + You must own the type to use <command>ALTER TYPE</command>. To change the schema of a type, you must also have <literal>CREATE</literal> privilege on the new schema. To alter the owner, you must also be a direct or indirect member of the new @@ -290,7 +290,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla <title>Notes</title> <para> - <command>ALTER TYPE ... ADD VALUE</> (the form that adds a new value to an + <command>ALTER TYPE ... ADD VALUE</command> (the form that adds a new value to an enum type) cannot be executed inside a transaction block. </para> @@ -301,7 +301,7 @@ ALTER TYPE <replaceable class="parameter">name</replaceable> RENAME VALUE <repla is used to set the new value's 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 <quote>wrapped - around</> since the original creation of the enum type). The slowdown is + around</quote> 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 reloading the database. diff --git a/doc/src/sgml/ref/alter_user_mapping.sgml b/doc/src/sgml/ref/alter_user_mapping.sgml index 5cc49210edb..18271d51995 100644 --- a/doc/src/sgml/ref/alter_user_mapping.sgml +++ b/doc/src/sgml/ref/alter_user_mapping.sgml @@ -38,7 +38,7 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <para> 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 <literal>USAGE</> privilege on the server has + their own user name if <literal>USAGE</literal> privilege on the server has been granted to the user. </para> </refsect1> @@ -51,9 +51,9 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <term><replaceable class="parameter">user_name</replaceable></term> <listitem> <para> - User name of the mapping. <literal>CURRENT_USER</> - and <literal>USER</> match the name of the current - user. <literal>PUBLIC</> is used to match all present and future + User name of the mapping. <literal>CURRENT_USER</literal> + and <literal>USER</literal> match the name of the current + user. <literal>PUBLIC</literal> is used to match all present and future user names in the system. </para> </listitem> @@ -74,8 +74,8 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <para> Change options for the user mapping. The new options override any previously specified - options. <literal>ADD</>, <literal>SET</>, and <literal>DROP</> - specify the action to be performed. <literal>ADD</> is assumed + options. <literal>ADD</literal>, <literal>SET</literal>, and <literal>DROP</literal> + specify the action to be performed. <literal>ADD</literal> is assumed if no operation is explicitly specified. Option names must be unique; options are also validated by the server's foreign-data wrapper. @@ -89,7 +89,7 @@ ALTER USER MAPPING FOR { <replaceable class="parameter">user_name</replaceable> <title>Examples</title> <para> - Change the password for user mapping <literal>bob</>, server <literal>foo</>: + Change the password for user mapping <literal>bob</literal>, server <literal>foo</literal>: <programlisting> ALTER USER MAPPING FOR bob SERVER foo OPTIONS (SET password 'public'); </programlisting></para> diff --git a/doc/src/sgml/ref/alter_view.sgml b/doc/src/sgml/ref/alter_view.sgml index 788eda5d58e..e7180b44093 100644 --- a/doc/src/sgml/ref/alter_view.sgml +++ b/doc/src/sgml/ref/alter_view.sgml @@ -37,12 +37,12 @@ ALTER VIEW [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RESET <para> <command>ALTER VIEW</command> changes various auxiliary properties of a view. (If you want to modify the view's defining query, - use <command>CREATE OR REPLACE VIEW</>.) + use <command>CREATE OR REPLACE VIEW</command>.) </para> <para> - You must own the view to use <command>ALTER VIEW</>. - To change a view's schema, you must also have <literal>CREATE</> + You must own the view to use <command>ALTER VIEW</command>. + To change a view's schema, you must also have <literal>CREATE</literal> 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 <literal>CREATE</literal> privilege on @@ -81,7 +81,7 @@ ALTER VIEW [ IF EXISTS ] <replaceable class="parameter">name</replaceable> RESET <para> These forms set or remove the default value for a column. A view column's default value is substituted into any - <command>INSERT</> or <command>UPDATE</> command whose target is the + <command>INSERT</command> or <command>UPDATE</command> command whose target is the view, before applying any rules or triggers for the view. The view's default will therefore take precedence over any default values from underlying relations. @@ -185,7 +185,7 @@ INSERT INTO a_view(id) VALUES(2); -- ts will receive the current time <title>Compatibility</title> <para> - <command>ALTER VIEW</command> is a <productname>PostgreSQL</> + <command>ALTER VIEW</command> is a <productname>PostgreSQL</productname> extension of the SQL standard. </para> </refsect1> diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml index eae7fe92e09..12f2f093372 100644 --- a/doc/src/sgml/ref/analyze.sgml +++ b/doc/src/sgml/ref/analyze.sgml @@ -35,7 +35,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> <command>ANALYZE</command> collects statistics about the contents of tables in the database, and stores the results in the <link - linkend="catalog-pg-statistic"><structname>pg_statistic</></> + linkend="catalog-pg-statistic"><structname>pg_statistic</structname></link> system catalog. Subsequently, the query planner uses these statistics to help determine the most efficient execution plans for queries. @@ -93,7 +93,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <title>Outputs</title> <para> - When <literal>VERBOSE</> is specified, <command>ANALYZE</> emits + When <literal>VERBOSE</literal> is specified, <command>ANALYZE</command> emits progress messages to indicate which table is currently being processed. Various statistics about the tables are printed as well. </para> @@ -104,8 +104,8 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> Foreign tables are analyzed only when explicitly selected. Not all - foreign data wrappers support <command>ANALYZE</>. If the table's - wrapper does not support <command>ANALYZE</>, the command prints a + foreign data wrappers support <command>ANALYZE</command>. If the table's + wrapper does not support <command>ANALYZE</command>, the command prints a warning and does nothing. </para> @@ -172,8 +172,8 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <literal>pg_statistic</literal>. 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 <literal>WHERE</>, <literal>GROUP BY</>, - or <literal>ORDER BY</> clauses of queries, since the planner will + never used as part of the <literal>WHERE</literal>, <literal>GROUP BY</literal>, + or <literal>ORDER BY</literal> clauses of queries, since the planner will have no use for statistics on such columns. </para> @@ -191,7 +191,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea 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 - <command>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</> + <command>ALTER TABLE ... ALTER COLUMN ... SET (n_distinct = ...)</command> (see <xref linkend="sql-altertable">). </para> @@ -210,7 +210,7 @@ ANALYZE [ VERBOSE ] [ <replaceable class="parameter">table_and_columns</replacea <para> If any of the child tables are foreign tables whose foreign data wrappers - do not support <command>ANALYZE</>, those child tables are ignored while + do not support <command>ANALYZE</command>, those child tables are ignored while gathering inheritance statistics. </para> diff --git a/doc/src/sgml/ref/begin.sgml b/doc/src/sgml/ref/begin.sgml index c04f1c8064c..fd6f073d18e 100644 --- a/doc/src/sgml/ref/begin.sgml +++ b/doc/src/sgml/ref/begin.sgml @@ -91,7 +91,7 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</ <para> <xref linkend="sql-start-transaction"> has the same functionality - as <command>BEGIN</>. + as <command>BEGIN</command>. </para> <para> @@ -101,7 +101,7 @@ BEGIN [ WORK | TRANSACTION ] [ <replaceable class="parameter">transaction_mode</ </para> <para> - Issuing <command>BEGIN</> when already inside a transaction block will + Issuing <command>BEGIN</command> 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 <xref linkend="sql-savepoint">). diff --git a/doc/src/sgml/ref/close.sgml b/doc/src/sgml/ref/close.sgml index aaa2f89a30f..4d71c45797d 100644 --- a/doc/src/sgml/ref/close.sgml +++ b/doc/src/sgml/ref/close.sgml @@ -90,7 +90,7 @@ CLOSE { <replaceable class="parameter">name</replaceable> | ALL } <para> You can see all available cursors by querying the <link - linkend="view-pg-cursors"><structname>pg_cursors</></> system view. + linkend="view-pg-cursors"><structname>pg_cursors</structname></link> system view. </para> <para> @@ -115,7 +115,7 @@ CLOSE liahona; <para> <command>CLOSE</command> is fully conforming with the SQL - standard. <command>CLOSE ALL</> is a <productname>PostgreSQL</> + standard. <command>CLOSE ALL</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml index b55734d35c9..5c5db750771 100644 --- a/doc/src/sgml/ref/cluster.sgml +++ b/doc/src/sgml/ref/cluster.sgml @@ -128,7 +128,7 @@ CLUSTER [VERBOSE] </para> <para> - <command>CLUSTER</> can re-sort the table using either an index scan + <command>CLUSTER</command> 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 @@ -148,13 +148,13 @@ CLUSTER [VERBOSE] 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 <xref - linkend="guc-enable-sort"> to <literal>off</>. + linkend="guc-enable-sort"> to <literal>off</literal>. </para> <para> It is advisable to set <xref linkend="guc-maintenance-work-mem"> to a reasonably large value (but not more than the amount of RAM you can - dedicate to the <command>CLUSTER</> operation) before clustering. + dedicate to the <command>CLUSTER</command> operation) before clustering. </para> <para> @@ -168,7 +168,7 @@ CLUSTER [VERBOSE] Because <command>CLUSTER</command> 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 - <command>CLUSTER</> without any parameters, so that the desired tables + <command>CLUSTER</command> without any parameters, so that the desired tables are periodically reclustered. </para> @@ -212,7 +212,7 @@ CLUSTER; <synopsis> CLUSTER <replaceable class="parameter">index_name</replaceable> ON <replaceable class="parameter">table_name</replaceable> </synopsis> - is also supported for compatibility with pre-8.3 <productname>PostgreSQL</> + is also supported for compatibility with pre-8.3 <productname>PostgreSQL</productname> versions. </para> </refsect1> diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml index 67582fd6e69..081bbc5f7a3 100644 --- a/doc/src/sgml/ref/clusterdb.sgml +++ b/doc/src/sgml/ref/clusterdb.sgml @@ -76,8 +76,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-a</></term> - <term><option>--all</></term> + <term><option>-a</option></term> + <term><option>--all</option></term> <listitem> <para> Cluster all databases. @@ -86,8 +86,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term> - <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></></term> + <term><option><optional>-d</optional> <replaceable class="parameter">dbname</replaceable></option></term> + <term><option><optional>--dbname=</optional><replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to be clustered. @@ -101,8 +101,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>clusterdb</application> generates @@ -112,8 +112,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-q</></term> - <term><option>--quiet</></term> + <term><option>-q</option></term> + <term><option>--quiet</option></term> <listitem> <para> Do not display progress messages. @@ -122,20 +122,20 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-t <replaceable class="parameter">table</replaceable></></term> - <term><option>--table=<replaceable class="parameter">table</replaceable></></term> + <term><option>-t <replaceable class="parameter">table</replaceable></option></term> + <term><option>--table=<replaceable class="parameter">table</replaceable></option></term> <listitem> <para> Cluster <replaceable class="parameter">table</replaceable> only. Multiple tables can be clustered by writing multiple - <option>-t</> switches. + <option>-t</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-v</></term> - <term><option>--verbose</></term> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> <para> Print detailed information during processing. @@ -144,8 +144,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>clusterdb</application> version and exit. @@ -154,8 +154,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>clusterdb</application> command line @@ -173,8 +173,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the server is @@ -185,8 +185,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -197,8 +197,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -207,8 +207,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -222,8 +222,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>clusterdb</application> to prompt for a @@ -236,14 +236,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>clusterdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to discover what other @@ -277,8 +277,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/comment.sgml b/doc/src/sgml/ref/comment.sgml index 059d6f41d81..ab2e09d5218 100644 --- a/doc/src/sgml/ref/comment.sgml +++ b/doc/src/sgml/ref/comment.sgml @@ -83,16 +83,16 @@ COMMENT ON <para> Only one comment string is stored for each object, so to modify a comment, - issue a new <command>COMMENT</> command for the same object. To remove a + issue a new <command>COMMENT</command> command for the same object. To remove a comment, write <literal>NULL</literal> in place of the text string. Comments are automatically dropped when their object is dropped. </para> <para> For most kinds of object, only the object's owner can set the comment. - Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</> is + Roles don't have owners, so the rule for <literal>COMMENT ON ROLE</literal> is that you must be superuser to comment on a superuser role, or have the - <literal>CREATEROLE</> privilege to comment on non-superuser roles. + <literal>CREATEROLE</literal> privilege to comment on non-superuser roles. Likewise, access methods don't have owners either; you must be superuser to comment on an access method. Of course, a superuser can comment on anything. @@ -103,8 +103,8 @@ COMMENT ON <command>\d</command> family of commands. Other user interfaces to retrieve comments can be built atop the same built-in functions that <application>psql</application> uses, namely - <function>obj_description</>, <function>col_description</>, - and <function>shobj_description</> + <function>obj_description</function>, <function>col_description</function>, + and <function>shobj_description</function> (see <xref linkend="functions-info-comment-table">). </para> </refsect1> @@ -171,14 +171,14 @@ COMMENT ON <listitem> <para> The mode of a function or aggregate - argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>COMMENT</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -219,7 +219,7 @@ COMMENT ON <listitem> <para> The data type(s) of the operator's arguments (optionally - schema-qualified). Write <literal>NONE</> for the missing argument + schema-qualified). Write <literal>NONE</literal> for the missing argument of a prefix or postfix operator. </para> </listitem> @@ -258,7 +258,7 @@ COMMENT ON <term><replaceable class="parameter">text</replaceable></term> <listitem> <para> - The new comment, written as a string literal; or <literal>NULL</> + The new comment, written as a string literal; or <literal>NULL</literal> to drop the comment. </para> </listitem> diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index e93c216849b..8e3f53957ee 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -60,7 +60,7 @@ COMMIT [ WORK | TRANSACTION ] </para> <para> - Issuing <command>COMMIT</> when not inside a transaction does + Issuing <command>COMMIT</command> when not inside a transaction does no harm, but it will provoke a warning message. </para> </refsect1> diff --git a/doc/src/sgml/ref/commit_prepared.sgml b/doc/src/sgml/ref/commit_prepared.sgml index 716aed3ac22..35bbf85af7e 100644 --- a/doc/src/sgml/ref/commit_prepared.sgml +++ b/doc/src/sgml/ref/commit_prepared.sgml @@ -75,7 +75,7 @@ COMMIT PREPARED <replaceable class="parameter">transaction_id</replaceable> <title id="sql-commit-prepared-examples-title">Examples</title> <para> Commit the transaction identified by the transaction - identifier <literal>foobar</>: + identifier <literal>foobar</literal>: <programlisting> COMMIT PREPARED 'foobar'; diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml index 732efe69e66..8f0974b2569 100644 --- a/doc/src/sgml/ref/copy.sgml +++ b/doc/src/sgml/ref/copy.sgml @@ -54,10 +54,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <command>COPY</command> moves data between <productname>PostgreSQL</productname> tables and standard file-system files. <command>COPY TO</command> copies the contents of a table - <emphasis>to</> a file, while <command>COPY FROM</command> copies - data <emphasis>from</> a file to a table (appending the data to + <emphasis>to</emphasis> a file, while <command>COPY FROM</command> copies + data <emphasis>from</emphasis> a file to a table (appending the data to whatever is in the table already). <command>COPY TO</command> - can also copy the results of a <command>SELECT</> query. + can also copy the results of a <command>SELECT</command> query. </para> <para> @@ -118,10 +118,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable copied. Note that parentheses are required around the query. </para> <para> - For <command>INSERT</>, <command>UPDATE</> and - <command>DELETE</> queries a RETURNING clause must be provided, + For <command>INSERT</command>, <command>UPDATE</command> and + <command>DELETE</command> queries a RETURNING clause must be provided, and the target relation must not have a conditional rule, nor - an <literal>ALSO</> rule, nor an <literal>INSTEAD</> rule + an <literal>ALSO</literal> rule, nor an <literal>INSTEAD</literal> rule that expands to multiple statements. </para> </listitem> @@ -133,7 +133,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <para> 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 <literal>E''</> string and + path. Windows users might need to use an <literal>E''</literal> string and double any backslashes used in the path name. </para> </listitem> @@ -144,7 +144,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> A command to execute. In <command>COPY FROM</command>, the input is - read from standard output of the command, and in <command>COPY TO</>, + read from standard output of the command, and in <command>COPY TO</command>, the output is written to the standard input of the command. </para> <para> @@ -181,9 +181,9 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Specifies whether the selected option should be turned on or off. - You can write <literal>TRUE</literal>, <literal>ON</>, or + You can write <literal>TRUE</literal>, <literal>ON</literal>, or <literal>1</literal> to enable the option, and <literal>FALSE</literal>, - <literal>OFF</>, or <literal>0</literal> to disable it. The + <literal>OFF</literal>, or <literal>0</literal> to disable it. The <replaceable class="parameter">boolean</replaceable> value can also be omitted, in which case <literal>TRUE</literal> is assumed. </para> @@ -195,10 +195,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Selects the data format to be read or written: - <literal>text</>, - <literal>csv</> (Comma Separated Values), - or <literal>binary</>. - The default is <literal>text</>. + <literal>text</literal>, + <literal>csv</literal> (Comma Separated Values), + or <literal>binary</literal>. + The default is <literal>text</literal>. </para> </listitem> </varlistentry> @@ -220,7 +220,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Requests copying the data with rows already frozen, just as they - would be after running the <command>VACUUM FREEZE</> command. + would be after running the <command>VACUUM FREEZE</command> 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 @@ -241,9 +241,9 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <para> 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 <literal>CSV</> format. + a comma in <literal>CSV</literal> format. This must be a single one-byte character. - This option is not allowed when using <literal>binary</> format. + This option is not allowed when using <literal>binary</literal> format. </para> </listitem> </varlistentry> @@ -254,10 +254,10 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <para> Specifies the string that represents a null value. The default is <literal>\N</literal> (backslash-N) in text format, and an unquoted empty - string in <literal>CSV</> format. You might prefer an + string in <literal>CSV</literal> format. You might prefer an empty string even in text format for cases where you don't want to distinguish nulls from empty strings. - This option is not allowed when using <literal>binary</> format. + This option is not allowed when using <literal>binary</literal> format. </para> <note> @@ -279,7 +279,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable 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, and on input, the first line is ignored. - This option is allowed only when using <literal>CSV</> format. + This option is allowed only when using <literal>CSV</literal> format. </para> </listitem> </varlistentry> @@ -291,7 +291,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable 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 <literal>CSV</> format. + This option is allowed only when using <literal>CSV</literal> format. </para> </listitem> </varlistentry> @@ -301,59 +301,59 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <listitem> <para> Specifies the character that should appear before a - data character that matches the <literal>QUOTE</> value. - The default is the same as the <literal>QUOTE</> value (so that + data character that matches the <literal>QUOTE</literal> value. + The default is the same as the <literal>QUOTE</literal> 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 <literal>CSV</> format. + This option is allowed only when using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>FORCE_QUOTE</></term> + <term><literal>FORCE_QUOTE</literal></term> <listitem> <para> Forces quoting to be - used for all non-<literal>NULL</> values in each specified column. - <literal>NULL</> output is never quoted. If <literal>*</> is specified, - non-<literal>NULL</> values will be quoted in all columns. - This option is allowed only in <command>COPY TO</>, and only when - using <literal>CSV</> format. + used for all non-<literal>NULL</literal> values in each specified column. + <literal>NULL</literal> output is never quoted. If <literal>*</literal> is specified, + non-<literal>NULL</literal> values will be quoted in all columns. + This option is allowed only in <command>COPY TO</command>, and only when + using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>FORCE_NOT_NULL</></term> + <term><literal>FORCE_NOT_NULL</literal></term> <listitem> <para> Do not match the specified columns' 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 <command>COPY FROM</>, and only when - using <literal>CSV</> format. + This option is allowed only in <command>COPY FROM</command>, and only when + using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>FORCE_NULL</></term> + <term><literal>FORCE_NULL</literal></term> <listitem> <para> Match the specified columns' values against the null string, even if it has been quoted, and if a match is found set the value to - <literal>NULL</>. In the default case where the null string is empty, + <literal>NULL</literal>. In the default case where the null string is empty, this converts a quoted empty string into NULL. - This option is allowed only in <command>COPY FROM</>, and only when - using <literal>CSV</> format. + This option is allowed only in <command>COPY FROM</command>, and only when + using <literal>CSV</literal> format. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>ENCODING</></term> + <term><literal>ENCODING</literal></term> <listitem> <para> Specifies that the file is encoded in the <replaceable @@ -371,7 +371,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable <title>Outputs</title> <para> - On successful completion, a <command>COPY</> command returns a command + On successful completion, a <command>COPY</command> command returns a command tag of the form <screen> COPY <replaceable class="parameter">count</replaceable> @@ -382,10 +382,10 @@ COPY <replaceable class="parameter">count</replaceable> <note> <para> - <application>psql</> will print this command tag only if the command - was not <literal>COPY ... TO STDOUT</>, or the - equivalent <application>psql</> meta-command - <literal>\copy ... to stdout</>. This is to prevent confusing the + <application>psql</application> will print this command tag only if the command + was not <literal>COPY ... TO STDOUT</literal>, or the + equivalent <application>psql</application> meta-command + <literal>\copy ... to stdout</literal>. This is to prevent confusing the command tag with the data that was just printed. </para> </note> @@ -403,16 +403,16 @@ COPY <replaceable class="parameter">count</replaceable> <para> <command>COPY FROM</command> can be used with plain tables and with views - that have <literal>INSTEAD OF INSERT</> triggers. + that have <literal>INSTEAD OF INSERT</literal> triggers. </para> <para> <command>COPY</command> only deals with the specific table named; it does not copy data to or from child tables. Thus for example - <literal>COPY <replaceable class="parameter">table</> TO</literal> + <literal>COPY <replaceable class="parameter">table</replaceable> TO</literal> shows the same data as <literal>SELECT * FROM ONLY <replaceable - class="parameter">table</></literal>. But <literal>COPY - (SELECT * FROM <replaceable class="parameter">table</>) TO ...</literal> + class="parameter">table</replaceable></literal>. But <literal>COPY + (SELECT * FROM <replaceable class="parameter">table</replaceable>) TO ...</literal> can be used to dump all of the data in an inheritance hierarchy. </para> @@ -427,7 +427,7 @@ COPY <replaceable class="parameter">count</replaceable> <para> If row-level security is enabled for the table, the relevant <command>SELECT</command> policies will apply to <literal>COPY - <replaceable class="parameter">table</> TO</literal> statements. + <replaceable class="parameter">table</replaceable> TO</literal> statements. Currently, <command>COPY FROM</command> is not supported for tables with row-level security. Use equivalent <command>INSERT</command> statements instead. @@ -491,10 +491,10 @@ COPY <replaceable class="parameter">count</replaceable> <varname>DateStyle</varname>. To ensure portability to other <productname>PostgreSQL</productname> installations that might use non-default <varname>DateStyle</varname> settings, - <varname>DateStyle</varname> should be set to <literal>ISO</> before - using <command>COPY TO</>. It is also a good idea to avoid dumping + <varname>DateStyle</varname> should be set to <literal>ISO</literal> before + using <command>COPY TO</command>. It is also a good idea to avoid dumping data with <varname>IntervalStyle</varname> set to - <literal>sql_standard</>, because negative interval values might be + <literal>sql_standard</literal>, because negative interval values might be misinterpreted by a server that has a different setting for <varname>IntervalStyle</varname>. </para> @@ -519,7 +519,7 @@ COPY <replaceable class="parameter">count</replaceable> </para> <para> - <literal>FORCE_NULL</> and <literal>FORCE_NOT_NULL</> can be used + <literal>FORCE_NULL</literal> and <literal>FORCE_NOT_NULL</literal> 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. </para> @@ -533,7 +533,7 @@ COPY <replaceable class="parameter">count</replaceable> <title>Text Format</title> <para> - When the <literal>text</> format is used, + When the <literal>text</literal> 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 @@ -548,17 +548,17 @@ COPY <replaceable class="parameter">count</replaceable> <para> End of data can be represented by a single line containing just - backslash-period (<literal>\.</>). An end-of-data marker is + backslash-period (<literal>\.</literal>). 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. </para> <para> - Backslash characters (<literal>\</>) can be used in the + Backslash characters (<literal>\</literal>) can be used in the <command>COPY</command> data to quote data characters that might otherwise be taken as row or column delimiters. In particular, the - following characters <emphasis>must</> be preceded by a backslash if + following characters <emphasis>must</emphasis> be preceded by a backslash if they appear as part of a column value: backslash itself, newline, carriage return, and the current delimiter character. </para> @@ -587,37 +587,37 @@ COPY <replaceable class="parameter">count</replaceable> <tbody> <row> - <entry><literal>\b</></entry> + <entry><literal>\b</literal></entry> <entry>Backspace (ASCII 8)</entry> </row> <row> - <entry><literal>\f</></entry> + <entry><literal>\f</literal></entry> <entry>Form feed (ASCII 12)</entry> </row> <row> - <entry><literal>\n</></entry> + <entry><literal>\n</literal></entry> <entry>Newline (ASCII 10)</entry> </row> <row> - <entry><literal>\r</></entry> + <entry><literal>\r</literal></entry> <entry>Carriage return (ASCII 13)</entry> </row> <row> - <entry><literal>\t</></entry> + <entry><literal>\t</literal></entry> <entry>Tab (ASCII 9)</entry> </row> <row> - <entry><literal>\v</></entry> + <entry><literal>\v</literal></entry> <entry>Vertical tab (ASCII 11)</entry> </row> <row> - <entry><literal>\</><replaceable>digits</></entry> + <entry><literal>\</literal><replaceable>digits</replaceable></entry> <entry>Backslash followed by one to three octal digits specifies the character with that numeric code</entry> </row> <row> - <entry><literal>\x</><replaceable>digits</></entry> - <entry>Backslash <literal>x</> followed by one or two hex digits specifies + <entry><literal>\x</literal><replaceable>digits</replaceable></entry> + <entry>Backslash <literal>x</literal> followed by one or two hex digits specifies the character with that numeric code</entry> </row> </tbody> @@ -633,15 +633,15 @@ COPY <replaceable class="parameter">count</replaceable> 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 (<literal>\.</>) or the null string (<literal>\N</> by + end-of-data marker (<literal>\.</literal>) or the null string (<literal>\N</literal> by default). These strings will be recognized before any other backslash processing is done. </para> <para> It is strongly recommended that applications generating <command>COPY</command> data convert - data newlines and carriage returns to the <literal>\n</> and - <literal>\r</> sequences respectively. At present it is + data newlines and carriage returns to the <literal>\n</literal> and + <literal>\r</literal> 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. @@ -652,10 +652,10 @@ COPY <replaceable class="parameter">count</replaceable> <para> <command>COPY TO</command> will terminate each row with a Unix-style - newline (<quote><literal>\n</></>). Servers running on Microsoft Windows instead - output carriage return/newline (<quote><literal>\r\n</></>), but only for - <command>COPY</> to a server file; for consistency across platforms, - <command>COPY TO STDOUT</> always sends <quote><literal>\n</></> + newline (<quote><literal>\n</literal></quote>). Servers running on Microsoft Windows instead + output carriage return/newline (<quote><literal>\r\n</literal></quote>), but only for + <command>COPY</command> to a server file; for consistency across platforms, + <command>COPY TO STDOUT</command> always sends <quote><literal>\n</literal></quote> regardless of server platform. <command>COPY FROM</command> can handle lines ending with newlines, carriage returns, or carriage return/newlines. To reduce the risk of @@ -670,62 +670,62 @@ COPY <replaceable class="parameter">count</replaceable> <para> This format option is used for importing and exporting the Comma - Separated Value (<literal>CSV</>) file format used by many other + Separated Value (<literal>CSV</literal>) file format used by many other programs, such as spreadsheets. Instead of the escaping rules used by <productname>PostgreSQL</productname>'s standard text format, it produces and recognizes the common CSV escaping mechanism. </para> <para> - The values in each record are separated by the <literal>DELIMITER</> + The values in each record are separated by the <literal>DELIMITER</literal> character. If the value contains the delimiter character, the - <literal>QUOTE</> character, the <literal>NULL</> string, a carriage + <literal>QUOTE</literal> character, the <literal>NULL</literal> string, a carriage return, or line feed character, then the whole value is prefixed and - suffixed by the <literal>QUOTE</> character, and any occurrence - within the value of a <literal>QUOTE</> character or the - <literal>ESCAPE</> character is preceded by the escape character. - You can also use <literal>FORCE_QUOTE</> to force quotes when outputting - non-<literal>NULL</> values in specific columns. + suffixed by the <literal>QUOTE</literal> character, and any occurrence + within the value of a <literal>QUOTE</literal> character or the + <literal>ESCAPE</literal> character is preceded by the escape character. + You can also use <literal>FORCE_QUOTE</literal> to force quotes when outputting + non-<literal>NULL</literal> values in specific columns. </para> <para> - The <literal>CSV</> format has no standard way to distinguish a - <literal>NULL</> value from an empty string. - <productname>PostgreSQL</>'s <command>COPY</> handles this by quoting. - A <literal>NULL</> is output as the <literal>NULL</> parameter string - and is not quoted, while a non-<literal>NULL</> value matching the - <literal>NULL</> parameter string is quoted. For example, with the - default settings, a <literal>NULL</> is written as an unquoted empty + The <literal>CSV</literal> format has no standard way to distinguish a + <literal>NULL</literal> value from an empty string. + <productname>PostgreSQL</productname>'s <command>COPY</command> handles this by quoting. + A <literal>NULL</literal> is output as the <literal>NULL</literal> parameter string + and is not quoted, while a non-<literal>NULL</literal> value matching the + <literal>NULL</literal> parameter string is quoted. For example, with the + default settings, a <literal>NULL</literal> is written as an unquoted empty string, while an empty string data value is written with double quotes - (<literal>""</>). Reading values follows similar rules. You can - use <literal>FORCE_NOT_NULL</> to prevent <literal>NULL</> input + (<literal>""</literal>). Reading values follows similar rules. You can + use <literal>FORCE_NOT_NULL</literal> to prevent <literal>NULL</literal> input comparisons for specific columns. You can also use - <literal>FORCE_NULL</> to convert quoted null string data values to - <literal>NULL</>. + <literal>FORCE_NULL</literal> to convert quoted null string data values to + <literal>NULL</literal>. </para> <para> - Because backslash is not a special character in the <literal>CSV</> - format, <literal>\.</>, the end-of-data marker, could also appear - as a data value. To avoid any misinterpretation, a <literal>\.</> + Because backslash is not a special character in the <literal>CSV</literal> + format, <literal>\.</literal>, the end-of-data marker, could also appear + as a data value. To avoid any misinterpretation, a <literal>\.</literal> 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 <literal>\.</>, you might need to quote that value in the + value of <literal>\.</literal>, you might need to quote that value in the input file. </para> <note> <para> - In <literal>CSV</> format, all characters are significant. A quoted value + In <literal>CSV</literal> format, all characters are significant. A quoted value surrounded by white space, or any characters other than - <literal>DELIMITER</>, will include those characters. This can cause - errors if you import data from a system that pads <literal>CSV</> + <literal>DELIMITER</literal>, will include those characters. This can cause + errors if you import data from a system that pads <literal>CSV</literal> lines with white space out to some fixed width. If such a situation - arises you might need to preprocess the <literal>CSV</> file to remove + arises you might need to preprocess the <literal>CSV</literal> file to remove the trailing white space, before importing the data into - <productname>PostgreSQL</>. + <productname>PostgreSQL</productname>. </para> </note> @@ -743,7 +743,7 @@ COPY <replaceable class="parameter">count</replaceable> 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 <command>COPY</> might produce files that other + mechanism, and <command>COPY</command> might produce files that other programs cannot process. </para> </note> @@ -756,17 +756,17 @@ COPY <replaceable class="parameter">count</replaceable> <para> The <literal>binary</literal> format option causes all data to be stored/read as binary format rather than as text. It is - somewhat faster than the text and <literal>CSV</> formats, + somewhat faster than the text and <literal>CSV</literal> formats, but a binary-format file is less portable across machine architectures and <productname>PostgreSQL</productname> versions. Also, the binary format is very data type specific; for example - it will not work to output binary data from a <type>smallint</> column - and read it into an <type>integer</> column, even though that would work + it will not work to output binary data from a <type>smallint</type> column + and read it into an <type>integer</type> column, even though that would work fine in text format. </para> <para> - The <literal>binary</> file format consists + The <literal>binary</literal> 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. </para> @@ -790,7 +790,7 @@ COPY <replaceable class="parameter">count</replaceable> <term>Signature</term> <listitem> <para> -11-byte sequence <literal>PGCOPY\n\377\r\n\0</> — note that the zero byte +11-byte sequence <literal>PGCOPY\n\377\r\n\0</literal> — 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 @@ -804,7 +804,7 @@ filters, dropped zero bytes, dropped high bits, or parity changes.) <listitem> <para> 32-bit integer bit mask to denote important aspects of the file format. Bits -are numbered from 0 (<acronym>LSB</>) to 31 (<acronym>MSB</>). Note that +are numbered from 0 (<acronym>LSB</acronym>) to 31 (<acronym>MSB</acronym>). 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-31 are reserved to denote critical file format issues; a reader @@ -880,7 +880,7 @@ to be specified. <para> To determine the appropriate binary format for the actual tuple data you should consult the <productname>PostgreSQL</productname> source, in -particular the <function>*send</> and <function>*recv</> functions for +particular the <function>*send</function> and <function>*recv</function> functions for each column's data type (typically these functions are found in the <filename>src/backend/utils/adt/</filename> directory of the source distribution). @@ -924,7 +924,7 @@ COPY country TO STDOUT (DELIMITER '|'); </para> <para> - To copy data from a file into the <literal>country</> table: + To copy data from a file into the <literal>country</literal> table: <programlisting> COPY country FROM '/usr1/proj/bray/sql/country_data'; </programlisting> @@ -986,7 +986,7 @@ ZW ZIMBABWE </para> <para> - The following syntax was used before <productname>PostgreSQL</> + The following syntax was used before <productname>PostgreSQL</productname> version 9.0 and is still supported: <synopsis> @@ -1015,13 +1015,13 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable [ FORCE QUOTE { <replaceable class="parameter">column_name</replaceable> [, ...] | * } ] ] ] </synopsis> - Note that in this syntax, <literal>BINARY</> and <literal>CSV</> are - treated as independent keywords, not as arguments of a <literal>FORMAT</> + Note that in this syntax, <literal>BINARY</literal> and <literal>CSV</literal> are + treated as independent keywords, not as arguments of a <literal>FORMAT</literal> option. </para> <para> - The following syntax was used before <productname>PostgreSQL</> + The following syntax was used before <productname>PostgreSQL</productname> version 7.3 and is still supported: <synopsis> diff --git a/doc/src/sgml/ref/create_access_method.sgml b/doc/src/sgml/ref/create_access_method.sgml index 891926dba54..1bb1a79bd23 100644 --- a/doc/src/sgml/ref/create_access_method.sgml +++ b/doc/src/sgml/ref/create_access_method.sgml @@ -73,7 +73,7 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable> <replaceable class="parameter">handler_function</replaceable> 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 <type>internal</>, + declared to take a single argument of type <type>internal</type>, and its return type depends on the type of access method; for <literal>INDEX</literal> access methods, it must be <type>index_am_handler</type>. The C-level API that the handler @@ -89,8 +89,8 @@ CREATE ACCESS METHOD <replaceable class="parameter">name</replaceable> <title>Examples</title> <para> - Create an index access method <literal>heptree</> with - handler function <literal>heptree_handler</>: + Create an index access method <literal>heptree</literal> with + handler function <literal>heptree_handler</literal>: <programlisting> CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler; </programlisting></para> @@ -101,7 +101,7 @@ CREATE ACCESS METHOD heptree TYPE INDEX HANDLER heptree_handler; <para> <command>CREATE ACCESS METHOD</command> is a - <productname>PostgreSQL</> extension. + <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_aggregate.sgml b/doc/src/sgml/ref/create_aggregate.sgml index ee79c90df2b..3de30fa5808 100644 --- a/doc/src/sgml/ref/create_aggregate.sgml +++ b/doc/src/sgml/ref/create_aggregate.sgml @@ -98,7 +98,7 @@ CREATE AGGREGATE <replaceable class="parameter">name</replaceable> ( <para> If a schema name is given (for example, <literal>CREATE AGGREGATE - myschema.myagg ...</>) then the aggregate function is created in the + myschema.myagg ...</literal>) then the aggregate function is created in the specified schema. Otherwise it is created in the current schema. </para> @@ -191,57 +191,57 @@ CREATE AGGREGATE <replaceable class="parameter">name</replaceable> ( is polymorphic and the state value's 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 <literal>FINALFUNC_EXTRA</> option is used), but nonetheless they + the <literal>FINALFUNC_EXTRA</literal> option is used), but nonetheless they are valid parameters. The final function could for example make use - of <function>get_fn_expr_argtype</> to identify the actual argument type + of <function>get_fn_expr_argtype</function> to identify the actual argument type in the current call. </para> <para> - An aggregate can optionally support <firstterm>moving-aggregate mode</>, + An aggregate can optionally support <firstterm>moving-aggregate mode</firstterm>, as described in <xref linkend="xaggr-moving-aggregates">. This requires - specifying the <literal>MSFUNC</>, <literal>MINVFUNC</>, - and <literal>MSTYPE</> parameters, and optionally - the <literal>MSPACE</>, <literal>MFINALFUNC</>, - <literal>MFINALFUNC_EXTRA</>, <literal>MFINALFUNC_MODIFY</>, - and <literal>MINITCOND</> parameters. Except for <literal>MINVFUNC</>, + specifying the <literal>MSFUNC</literal>, <literal>MINVFUNC</literal>, + and <literal>MSTYPE</literal> parameters, and optionally + the <literal>MSPACE</literal>, <literal>MFINALFUNC</literal>, + <literal>MFINALFUNC_EXTRA</literal>, <literal>MFINALFUNC_MODIFY</literal>, + and <literal>MINITCOND</literal> parameters. Except for <literal>MINVFUNC</literal>, these parameters work like the corresponding simple-aggregate parameters - without <literal>M</>; they define a separate implementation of the + without <literal>M</literal>; they define a separate implementation of the aggregate that includes an inverse transition function. </para> <para> The syntax with <literal>ORDER BY</literal> in the parameter list creates a special type of aggregate called an <firstterm>ordered-set - aggregate</firstterm>; or if <literal>HYPOTHETICAL</> is specified, then + aggregate</firstterm>; or if <literal>HYPOTHETICAL</literal> is specified, then a <firstterm>hypothetical-set aggregate</firstterm> 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 <firstterm>direct</> arguments, which are + call. Also, they can have <firstterm>direct</firstterm> 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 <quote>hypothetical</> row. + aggregate-input rows as an additional <quote>hypothetical</quote> row. </para> <para> - An aggregate can optionally support <firstterm>partial aggregation</>, + An aggregate can optionally support <firstterm>partial aggregation</firstterm>, as described in <xref linkend="xaggr-partial-aggregates">. - This requires specifying the <literal>COMBINEFUNC</> parameter. + This requires specifying the <literal>COMBINEFUNC</literal> parameter. If the <replaceable class="parameter">state_data_type</replaceable> - is <type>internal</>, it's usually also appropriate to provide the - <literal>SERIALFUNC</> and <literal>DESERIALFUNC</> parameters so that + is <type>internal</type>, it's usually also appropriate to provide the + <literal>SERIALFUNC</literal> and <literal>DESERIALFUNC</literal> parameters so that parallel aggregation is possible. Note that the aggregate must also be - marked <literal>PARALLEL SAFE</> to enable parallel aggregation. + marked <literal>PARALLEL SAFE</literal> to enable parallel aggregation. </para> <para> - Aggregates that behave like <function>MIN</> or <function>MAX</> can + Aggregates that behave like <function>MIN</function> or <function>MAX</function> 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 <firstterm>sort operator</>. The basic requirement is that + specifying a <firstterm>sort operator</firstterm>. The basic requirement is that the aggregate must yield the first element in the sort ordering induced by the operator; in other words: <programlisting> @@ -253,9 +253,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </programlisting> 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's <literal><</> operator is the proper sort - operator for <function>MIN</>, and <literal>></> is the proper sort - operator for <function>MAX</>. Note that the optimization will never + Ordinarily, a data type's <literal><</literal> operator is the proper sort + operator for <function>MIN</function>, and <literal>></literal> is the proper sort + operator for <function>MAX</function>. Note that the optimization will never actually take effect unless the specified operator is the <quote>less than</quote> or <quote>greater than</quote> strategy member of a B-tree index operator class. @@ -288,10 +288,10 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> - The mode of an argument: <literal>IN</> or <literal>VARIADIC</>. - (Aggregate functions do not support <literal>OUT</> arguments.) - If omitted, the default is <literal>IN</>. Only the last argument - can be marked <literal>VARIADIC</>. + The mode of an argument: <literal>IN</literal> or <literal>VARIADIC</literal>. + (Aggregate functions do not support <literal>OUT</literal> arguments.) + If omitted, the default is <literal>IN</literal>. Only the last argument + can be marked <literal>VARIADIC</literal>. </para> </listitem> </varlistentry> @@ -312,7 +312,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> An input data type on which this aggregate function operates. - To create a zero-argument aggregate function, write <literal>*</> + To create a zero-argument aggregate function, write <literal>*</literal> in place of the list of argument specifications. (An example of such an aggregate is <function>count(*)</function>.) </para> @@ -323,12 +323,12 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <term><replaceable class="parameter">base_type</replaceable></term> <listitem> <para> - In the old syntax for <command>CREATE AGGREGATE</>, the input data type - is specified by a <literal>basetype</> parameter rather than being + In the old syntax for <command>CREATE AGGREGATE</command>, the input data type + is specified by a <literal>basetype</literal> 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 <literal>basetype</> as - <literal>"ANY"</> (not <literal>*</>). + with this syntax, specify the <literal>basetype</literal> as + <literal>"ANY"</literal> (not <literal>*</literal>). Ordered-set aggregates cannot be defined with the old syntax. </para> </listitem> @@ -339,9 +339,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> The name of the state transition function to be called for each - input row. For a normal <replaceable class="parameter">N</>-argument - aggregate function, the <replaceable class="parameter">sfunc</> - must take <replaceable class="parameter">N</>+1 arguments, + input row. For a normal <replaceable class="parameter">N</replaceable>-argument + aggregate function, the <replaceable class="parameter">sfunc</replaceable> + must take <replaceable class="parameter">N</replaceable>+1 arguments, the first being of type <replaceable class="parameter">state_data_type</replaceable> and the rest matching the declared input data type(s) of the aggregate. @@ -375,7 +375,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The approximate average size (in bytes) of the aggregate's state value. If this parameter is omitted or is zero, a default estimate is used - based on the <replaceable>state_data_type</>. + based on the <replaceable>state_data_type</replaceable>. The planner uses this value to estimate the memory required for a grouped aggregate query. The planner will consider using hash aggregation for such a query only if the hash table is estimated to fit @@ -408,7 +408,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </para> <para> - If <literal>FINALFUNC_EXTRA</> is specified, then in addition to the + If <literal>FINALFUNC_EXTRA</literal> 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's regular (aggregated) arguments. This is mainly useful to allow correct @@ -419,16 +419,16 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </varlistentry> <varlistentry> - <term><literal>FINALFUNC_MODIFY</> = { <literal>READ_ONLY</> | <literal>SHARABLE</> | <literal>READ_WRITE</> }</term> + <term><literal>FINALFUNC_MODIFY</literal> = { <literal>READ_ONLY</literal> | <literal>SHARABLE</literal> | <literal>READ_WRITE</literal> }</term> <listitem> <para> This option specifies whether the final function is a pure function - that does not modify its arguments. <literal>READ_ONLY</> indicates + that does not modify its arguments. <literal>READ_ONLY</literal> indicates it does not; the other two values indicate that it may change the transition state value. See <xref linkend="sql-createaggregate-notes" endterm="sql-createaggregate-notes-title"> below for more detail. The - default is <literal>READ_ONLY</>, except for ordered-set aggregates, - for which the default is <literal>READ_WRITE</>. + default is <literal>READ_ONLY</literal>, except for ordered-set aggregates, + for which the default is <literal>READ_WRITE</literal>. </para> </listitem> </varlistentry> @@ -482,11 +482,11 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> An aggregate function whose <replaceable class="parameter">state_data_type</replaceable> - is <type>internal</> can participate in parallel aggregation only if it + is <type>internal</type> can participate in parallel aggregation only if it has a <replaceable class="parameter">serialfunc</replaceable> function, - which must serialize the aggregate state into a <type>bytea</> value for + which must serialize the aggregate state into a <type>bytea</type> value for transmission to another process. This function must take a single - argument of type <type>internal</> and return type <type>bytea</>. A + argument of type <type>internal</type> and return type <type>bytea</type>. A corresponding <replaceable class="parameter">deserialfunc</replaceable> is also required. </para> @@ -499,9 +499,9 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> Deserialize a previously serialized aggregate state back into <replaceable class="parameter">state_data_type</replaceable>. This - function must take two arguments of types <type>bytea</> - and <type>internal</>, and produce a result of type <type>internal</>. - (Note: the second, <type>internal</> argument is unused, but is required + function must take two arguments of types <type>bytea</type> + and <type>internal</type>, and produce a result of type <type>internal</type>. + (Note: the second, <type>internal</type> argument is unused, but is required for type safety reasons.) </para> </listitem> @@ -526,8 +526,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; 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 <replaceable>mstate_data_type</>, which might be different - from <replaceable>state_data_type</>. + type <replaceable>mstate_data_type</replaceable>, which might be different + from <replaceable>state_data_type</replaceable>. </para> </listitem> </varlistentry> @@ -538,7 +538,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> 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 <replaceable>msfunc</>, but it is used to remove + result types as <replaceable>msfunc</replaceable>, 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. @@ -562,7 +562,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The approximate average size (in bytes) of the aggregate's state value, when using moving-aggregate mode. This works the same as - <replaceable>state_data_size</>. + <replaceable>state_data_size</replaceable>. </para> </listitem> </varlistentry> @@ -573,22 +573,22 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> The name of the final function called to compute the aggregate's result after all input rows have been traversed, when using - moving-aggregate mode. This works the same as <replaceable>ffunc</>, + moving-aggregate mode. This works the same as <replaceable>ffunc</replaceable>, except that its first argument's type - is <replaceable>mstate_data_type</> and extra dummy arguments are - specified by writing <literal>MFINALFUNC_EXTRA</>. - The aggregate result type determined by <replaceable>mffunc</> - or <replaceable>mstate_data_type</> must match that determined by the + is <replaceable>mstate_data_type</replaceable> and extra dummy arguments are + specified by writing <literal>MFINALFUNC_EXTRA</literal>. + The aggregate result type determined by <replaceable>mffunc</replaceable> + or <replaceable>mstate_data_type</replaceable> must match that determined by the aggregate's regular implementation. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>MFINALFUNC_MODIFY</> = { <literal>READ_ONLY</> | <literal>SHARABLE</> | <literal>READ_WRITE</> }</term> + <term><literal>MFINALFUNC_MODIFY</literal> = { <literal>READ_ONLY</literal> | <literal>SHARABLE</literal> | <literal>READ_WRITE</literal> }</term> <listitem> <para> - This option is like <literal>FINALFUNC_MODIFY</>, but it describes + This option is like <literal>FINALFUNC_MODIFY</literal>, but it describes the behavior of the moving-aggregate final function. </para> </listitem> @@ -599,7 +599,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <listitem> <para> The initial setting for the state value, when using moving-aggregate - mode. This works the same as <replaceable>initial_condition</>. + mode. This works the same as <replaceable>initial_condition</replaceable>. </para> </listitem> </varlistentry> @@ -608,8 +608,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <term><replaceable class="parameter">sort_operator</replaceable></term> <listitem> <para> - The associated sort operator for a <function>MIN</>- or - <function>MAX</>-like aggregate. + The associated sort operator for a <function>MIN</function>- or + <function>MAX</function>-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). @@ -618,14 +618,14 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </varlistentry> <varlistentry> - <term><literal>PARALLEL =</> { <literal>SAFE</> | <literal>RESTRICTED</> | <literal>UNSAFE</> }</term> + <term><literal>PARALLEL =</literal> { <literal>SAFE</literal> | <literal>RESTRICTED</literal> | <literal>UNSAFE</literal> }</term> <listitem> <para> - The meanings of <literal>PARALLEL SAFE</>, <literal>PARALLEL - RESTRICTED</>, and <literal>PARALLEL UNSAFE</> are the same as + The meanings of <literal>PARALLEL SAFE</literal>, <literal>PARALLEL + RESTRICTED</literal>, and <literal>PARALLEL UNSAFE</literal> are the same as in <xref linkend="sql-createfunction">. An aggregate will not be considered for parallelization if it is marked <literal>PARALLEL - UNSAFE</> (which is the default!) or <literal>PARALLEL RESTRICTED</>. + UNSAFE</literal> (which is the default!) or <literal>PARALLEL RESTRICTED</literal>. Note that the parallel-safety markings of the aggregate's support functions are not consulted by the planner, only the marking of the aggregate itself. @@ -640,7 +640,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; 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 (<literal>WITHIN GROUP</>) + match the data types of the aggregated (<literal>WITHIN GROUP</literal>) arguments. The <literal>HYPOTHETICAL</literal> flag has no effect on run-time behavior, only on parse-time resolution of the data types and collations of the aggregate's arguments. @@ -660,7 +660,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> In parameters that specify support function names, you can write - a schema name if needed, for example <literal>SFUNC = public.sum</>. + a schema name if needed, for example <literal>SFUNC = public.sum</literal>. Do not write argument types there, however — the argument types of the support functions are determined from other parameters. </para> @@ -668,7 +668,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> Ordinarily, PostgreSQL functions are expected to be true functions that do not modify their input values. However, an aggregate transition - function, <emphasis>when used in the context of an aggregate</>, + function, <emphasis>when used in the context of an aggregate</emphasis>, 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. @@ -678,26 +678,26 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; 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 <literal>FINALFUNC_MODIFY</> parameter. The <literal>READ_WRITE</> + the <literal>FINALFUNC_MODIFY</literal> parameter. The <literal>READ_WRITE</literal> 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 <literal>SHARABLE</> value indicates that the transition function + The <literal>SHARABLE</literal> 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 <literal>READ_WRITE</>.) + long as none of the final functions are marked <literal>READ_WRITE</literal>.) </para> <para> 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 <literal>UNBOUNDED PRECEDING</>). Conceptually, the forward + than <literal>UNBOUNDED PRECEDING</literal>). Conceptually, the forward transition function adds input values to the aggregate's 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, @@ -738,20 +738,20 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; </para> <para> - The syntax for ordered-set aggregates allows <literal>VARIADIC</> + The syntax for ordered-set aggregates allows <literal>VARIADIC</literal> to be specified for both the last direct parameter and the last - aggregated (<literal>WITHIN GROUP</>) parameter. However, the - current implementation restricts use of <literal>VARIADIC</> + aggregated (<literal>WITHIN GROUP</literal>) parameter. However, the + current implementation restricts use of <literal>VARIADIC</literal> in two ways. First, ordered-set aggregates can only use - <literal>VARIADIC "any"</>, not other variadic array types. - Second, if the last direct parameter is <literal>VARIADIC "any"</>, + <literal>VARIADIC "any"</literal>, not other variadic array types. + Second, if the last direct parameter is <literal>VARIADIC "any"</literal>, then there can be only one aggregated parameter and it must also - be <literal>VARIADIC "any"</>. (In the representation used in the + be <literal>VARIADIC "any"</literal>. (In the representation used in the system catalogs, these two parameters are merged into a single - <literal>VARIADIC "any"</> item, since <structname>pg_proc</> cannot - represent functions with more than one <literal>VARIADIC</> parameter.) + <literal>VARIADIC "any"</literal> item, since <structname>pg_proc</structname> cannot + represent functions with more than one <literal>VARIADIC</literal> parameter.) If the aggregate is a hypothetical-set aggregate, the direct arguments - that match the <literal>VARIADIC "any"</> parameter are the hypothetical + that match the <literal>VARIADIC "any"</literal> parameter are the hypothetical ones; any preceding parameters represent additional direct arguments that are not constrained to match the aggregated arguments. </para> @@ -764,7 +764,7 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1; <para> Partial (including parallel) aggregation is currently not supported for ordered-set aggregates. Also, it will never be used for aggregate calls - that include <literal>DISTINCT</> or <literal>ORDER BY</> clauses, since + that include <literal>DISTINCT</literal> or <literal>ORDER BY</literal> clauses, since those semantics cannot be supported during partial aggregation. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_cast.sgml b/doc/src/sgml/ref/create_cast.sgml index a7d13edc22b..89af1e50519 100644 --- a/doc/src/sgml/ref/create_cast.sgml +++ b/doc/src/sgml/ref/create_cast.sgml @@ -44,7 +44,7 @@ SELECT CAST(42 AS float8); </programlisting> converts the integer constant 42 to type <type>float8</type> by invoking a previously specified function, in this case - <literal>float8(int4)</>. (If no suitable cast has been defined, the + <literal>float8(int4)</literal>. (If no suitable cast has been defined, the conversion fails.) </para> @@ -64,7 +64,7 @@ SELECT CAST(42 AS float8); </para> <para> - You can define a cast as an <firstterm>I/O conversion cast</> by using + You can define a cast as an <firstterm>I/O conversion cast</firstterm> by using the <literal>WITH INOUT</literal> 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. @@ -75,14 +75,14 @@ SELECT CAST(42 AS float8); <para> By default, a cast can be invoked only by an explicit cast request, - that is an explicit <literal>CAST(<replaceable>x</> AS - <replaceable>typename</>)</literal> or - <replaceable>x</><literal>::</><replaceable>typename</> + that is an explicit <literal>CAST(<replaceable>x</replaceable> AS + <replaceable>typename</replaceable>)</literal> or + <replaceable>x</replaceable><literal>::</literal><replaceable>typename</replaceable> construct. </para> <para> - If the cast is marked <literal>AS ASSIGNMENT</> then it can be invoked + If the cast is marked <literal>AS ASSIGNMENT</literal> then it can be invoked implicitly when assigning a value to a column of the target data type. For example, supposing that <literal>foo.f1</literal> is a column of type <type>text</type>, then: @@ -90,13 +90,13 @@ SELECT CAST(42 AS float8); INSERT INTO foo (f1) VALUES (42); </programlisting> will be allowed if the cast from type <type>integer</type> to type - <type>text</type> is marked <literal>AS ASSIGNMENT</>, otherwise not. + <type>text</type> is marked <literal>AS ASSIGNMENT</literal>, otherwise not. (We generally use the term <firstterm>assignment cast</firstterm> to describe this kind of cast.) </para> <para> - If the cast is marked <literal>AS IMPLICIT</> then it can be invoked + If the cast is marked <literal>AS IMPLICIT</literal> then it can be invoked implicitly in any context, whether assignment or internally in an expression. (We generally use the term <firstterm>implicit cast</firstterm> to describe this kind of cast.) @@ -104,12 +104,12 @@ INSERT INTO foo (f1) VALUES (42); <programlisting> SELECT 2 + 4.0; </programlisting> - The parser initially marks the constants as being of type <type>integer</> - and <type>numeric</> respectively. There is no <type>integer</> - <literal>+</> <type>numeric</> operator in the system catalogs, - but there is a <type>numeric</> <literal>+</> <type>numeric</> operator. - The query will therefore succeed if a cast from <type>integer</> to - <type>numeric</> is available and is marked <literal>AS IMPLICIT</> — + The parser initially marks the constants as being of type <type>integer</type> + and <type>numeric</type> respectively. There is no <type>integer</type> + <literal>+</literal> <type>numeric</type> operator in the system catalogs, + but there is a <type>numeric</type> <literal>+</literal> <type>numeric</type> operator. + The query will therefore succeed if a cast from <type>integer</type> to + <type>numeric</type> is available and is marked <literal>AS IMPLICIT</literal> — which in fact it is. The parser will apply the implicit cast and resolve the query as if it had been written <programlisting> @@ -118,17 +118,17 @@ SELECT CAST ( 2 AS numeric ) + 4.0; </para> <para> - Now, the catalogs also provide a cast from <type>numeric</> to - <type>integer</>. If that cast were marked <literal>AS IMPLICIT</> — + Now, the catalogs also provide a cast from <type>numeric</type> to + <type>integer</type>. If that cast were marked <literal>AS IMPLICIT</literal> — which it is not — then the parser would be faced with choosing between the above interpretation and the alternative of casting the - <type>numeric</> constant to <type>integer</> and applying the - <type>integer</> <literal>+</> <type>integer</> operator. Lacking any + <type>numeric</type> constant to <type>integer</type> and applying the + <type>integer</type> <literal>+</literal> <type>integer</type> 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 <type>numeric</>-and-<type>integer</> expression as - <type>numeric</>; there is no built-in knowledge about that. + of a mixed <type>numeric</type>-and-<type>integer</type> expression as + <type>numeric</type>; there is no built-in knowledge about that. </para> <para> @@ -142,8 +142,8 @@ SELECT CAST ( 2 AS numeric ) + 4.0; general type category. For example, the cast from <type>int2</type> to <type>int4</type> can reasonably be implicit, but the cast from <type>float8</type> to <type>int4</type> should probably be - assignment-only. Cross-type-category casts, such as <type>text</> - to <type>int4</>, are best made explicit-only. + assignment-only. Cross-type-category casts, such as <type>text</type> + to <type>int4</type>, are best made explicit-only. </para> <note> @@ -151,8 +151,8 @@ SELECT CAST ( 2 AS numeric ) + 4.0; 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 <firstterm>type categories</> and <firstterm>preferred - types</> that can help to provide desired behavior in such cases. See + heuristic based on <firstterm>type categories</firstterm> and <firstterm>preferred + types</firstterm> that can help to provide desired behavior in such cases. See <xref linkend="sql-createtype"> for more information. </para> @@ -255,11 +255,11 @@ SELECT CAST ( 2 AS numeric ) + 4.0; Cast implementation functions can have one to three arguments. The first argument type must be identical to or binary-coercible from the cast's source type. The second argument, - if present, must be type <type>integer</>; it receives the type - modifier associated with the destination type, or <literal>-1</> + if present, must be type <type>integer</type>; it receives the type + modifier associated with the destination type, or <literal>-1</literal> if there is none. The third argument, - if present, must be type <type>boolean</>; it receives <literal>true</> - if the cast is an explicit cast, <literal>false</> otherwise. + if present, must be type <type>boolean</type>; it receives <literal>true</literal> + if the cast is an explicit cast, <literal>false</literal> 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 @@ -316,9 +316,9 @@ SELECT CAST ( 2 AS numeric ) + 4.0; <para> It is normally not necessary to create casts between user-defined types - and the standard string types (<type>text</>, <type>varchar</>, and - <type>char(<replaceable>n</>)</type>, as well as user-defined types that - are defined to be in the string category). <productname>PostgreSQL</> + and the standard string types (<type>text</type>, <type>varchar</type>, and + <type>char(<replaceable>n</replaceable>)</type>, as well as user-defined types that + are defined to be in the string category). <productname>PostgreSQL</productname> 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 @@ -338,11 +338,11 @@ SELECT CAST ( 2 AS numeric ) + 4.0; 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 - <replaceable>typename</>(<replaceable>x</>). This notation is in fact + <replaceable>typename</replaceable>(<replaceable>x</replaceable>). 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 <productname>PostgreSQL</> allows overloading of the same function + Since <productname>PostgreSQL</productname> 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's name. @@ -353,14 +353,14 @@ SELECT CAST ( 2 AS numeric ) + 4.0; 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 <replaceable>name</>(<replaceable>x</>) does not - exactly match any existing function, but <replaceable>name</> is the name - of a data type and <structname>pg_cast</> provides a binary-coercible cast - to this type from the type of <replaceable>x</>, then the call will be + If a function call <replaceable>name</replaceable>(<replaceable>x</replaceable>) does not + exactly match any existing function, but <replaceable>name</replaceable> is the name + of a data type and <structname>pg_cast</structname> provides a binary-coercible cast + to this type from the type of <replaceable>x</replaceable>, 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 - <structname>pg_cast</> entry but the cast would be to or from a string + <structname>pg_cast</structname> 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. @@ -372,7 +372,7 @@ SELECT CAST ( 2 AS numeric ) + 4.0; 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 - <literal>CAST</> or <literal>::</> notation). This exception was added + <literal>CAST</literal> or <literal>::</literal> 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. @@ -402,7 +402,7 @@ CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint) AS ASSIGNMENT; <acronym>SQL</acronym> standard, except that SQL does not make provisions for binary-coercible types or extra arguments to implementation functions. - <literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname> + <literal>AS IMPLICIT</literal> is a <productname>PostgreSQL</productname> extension, too. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_collation.sgml b/doc/src/sgml/ref/create_collation.sgml index f88758095f2..d4e99e925f0 100644 --- a/doc/src/sgml/ref/create_collation.sgml +++ b/doc/src/sgml/ref/create_collation.sgml @@ -116,7 +116,7 @@ CREATE COLLATION [ IF NOT EXISTS ] <replaceable>name</replaceable> FROM <replace <para> Specifies the provider to use for locale services associated with this collation. Possible values - are: <literal>icu</literal>,<indexterm><primary>ICU</></> + are: <literal>icu</literal>,<indexterm><primary>ICU</primary></indexterm> <literal>libc</literal>. <literal>libc</literal> is the default. The available choices depend on the operating system and build options. diff --git a/doc/src/sgml/ref/create_conversion.sgml b/doc/src/sgml/ref/create_conversion.sgml index d2e2c010ef3..03e0315eef7 100644 --- a/doc/src/sgml/ref/create_conversion.sgml +++ b/doc/src/sgml/ref/create_conversion.sgml @@ -29,7 +29,7 @@ CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable> <para> <command>CREATE CONVERSION</command> defines a new conversion between character set encodings. Also, conversions that - are marked <literal>DEFAULT</> can be used for automatic encoding + are marked <literal>DEFAULT</literal> can be used for automatic encoding conversion between client and server. For this purpose, two conversions, from encoding A to B <emphasis>and</emphasis> from encoding B to A, must be defined. @@ -51,7 +51,7 @@ CREATE [ DEFAULT ] CONVERSION <replaceable>name</replaceable> <listitem> <para> - The <literal>DEFAULT</> clause indicates that this conversion + The <literal>DEFAULT</literal> 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. @@ -137,7 +137,7 @@ conv_proc( <para> To create a conversion from encoding <literal>UTF8</literal> to - <literal>LATIN1</literal> using <function>myfunc</>: + <literal>LATIN1</literal> using <function>myfunc</function>: <programlisting> CREATE CONVERSION myconv FOR 'UTF8' TO 'LATIN1' FROM myfunc; </programlisting></para> diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml index 8e2a73402f4..8adfa3a37bf 100644 --- a/doc/src/sgml/ref/create_database.sgml +++ b/doc/src/sgml/ref/create_database.sgml @@ -44,21 +44,21 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <para> To create a database, you must be a superuser or have the special - <literal>CREATEDB</> privilege. + <literal>CREATEDB</literal> privilege. See <xref linkend="SQL-CREATEUSER">. </para> <para> By default, the new database will be created by cloning the standard - system database <literal>template1</>. A different template can be + system database <literal>template1</literal>. A different template can be specified by writing <literal>TEMPLATE <replaceable class="parameter">name</replaceable></literal>. In particular, - by writing <literal>TEMPLATE template0</>, you can create a virgin + by writing <literal>TEMPLATE template0</literal>, you can create a virgin database containing only the standard objects predefined by your version of <productname>PostgreSQL</productname>. This is useful if you wish to avoid copying any installation-local objects that might have been added to - <literal>template1</>. + <literal>template1</literal>. </para> </refsect1> @@ -115,7 +115,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <term><replaceable class="parameter">lc_collate</replaceable></term> <listitem> <para> - Collation order (<literal>LC_COLLATE</>) to use in the new database. + Collation order (<literal>LC_COLLATE</literal>) 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. @@ -127,7 +127,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <term><replaceable class="parameter">lc_ctype</replaceable></term> <listitem> <para> - Character classification (<literal>LC_CTYPE</>) to use in the new + Character classification (<literal>LC_CTYPE</literal>) 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. @@ -155,7 +155,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <para> If false then no one can connect to this database. The default is true, allowing connections (except as restricted by other mechanisms, - such as <literal>GRANT</>/<literal>REVOKE CONNECT</>). + such as <literal>GRANT</literal>/<literal>REVOKE CONNECT</literal>). </para> </listitem> </varlistentry> @@ -192,12 +192,12 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <command>CREATE DATABASE</> cannot be executed inside a transaction + <command>CREATE DATABASE</command> cannot be executed inside a transaction block. </para> <para> - Errors along the line of <quote>could not initialize database directory</> + Errors along the line of <quote>could not initialize database directory</quote> are most likely related to insufficient permissions on the data directory, a full disk, or other file system problems. </para> @@ -218,26 +218,26 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> </para> <para> - Although it is possible to copy a database other than <literal>template1</> + Although it is possible to copy a database other than <literal>template1</literal> by specifying its name as the template, this is not (yet) intended as a general-purpose <quote><command>COPY DATABASE</command></quote> facility. The principal limitation is that no other sessions can be connected to the template database while it is being copied. <command>CREATE - DATABASE</> will fail if any other connection exists when it starts; + DATABASE</command> will fail if any other connection exists when it starts; otherwise, new connections to the template database are locked out - until <command>CREATE DATABASE</> completes. + until <command>CREATE DATABASE</command> completes. See <xref linkend="manage-ag-templatedbs"> for more information. </para> <para> The character set encoding specified for the new database must be - compatible with the chosen locale settings (<literal>LC_COLLATE</> and - <literal>LC_CTYPE</>). If the locale is <literal>C</> (or equivalently - <literal>POSIX</>), then all encodings are allowed, but for other + compatible with the chosen locale settings (<literal>LC_COLLATE</literal> and + <literal>LC_CTYPE</literal>). If the locale is <literal>C</literal> (or equivalently + <literal>POSIX</literal>), 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.) - <command>CREATE DATABASE</> will allow superusers to specify - <literal>SQL_ASCII</> encoding regardless of the locale settings, + <command>CREATE DATABASE</command> will allow superusers to specify + <literal>SQL_ASCII</literal> 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. @@ -245,19 +245,19 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable> <para> The encoding and locale settings must match those of the template database, - except when <literal>template0</> is used as template. This is because + except when <literal>template0</literal> 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 - <literal>LC_COLLATE</> and <literal>LC_CTYPE</>. Copying such data would + <literal>LC_COLLATE</literal> and <literal>LC_CTYPE</literal>. Copying such data would result in a database that is corrupt according to the new settings. <literal>template0</literal>, however, is known to not contain any data or indexes that would be affected. </para> <para> - The <literal>CONNECTION LIMIT</> option is only enforced approximately; + The <literal>CONNECTION LIMIT</literal> option is only enforced approximately; if two new sessions start at about the same time when just one - connection <quote>slot</> remains for the database, it is possible that + connection <quote>slot</quote> remains for the database, it is possible that both will fail. Also, the limit is not enforced against superusers or background worker processes. </para> @@ -275,8 +275,8 @@ CREATE DATABASE lusiadas; </para> <para> - To create a database <literal>sales</> owned by user <literal>salesapp</> - with a default tablespace of <literal>salesspace</>: + To create a database <literal>sales</literal> owned by user <literal>salesapp</literal> + with a default tablespace of <literal>salesspace</literal>: <programlisting> CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; @@ -284,19 +284,19 @@ CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace; </para> <para> - To create a database <literal>music</> with a different locale: + To create a database <literal>music</literal> with a different locale: <programlisting> CREATE DATABASE music LC_COLLATE 'sv_SE.utf8' LC_CTYPE 'sv_SE.utf8' TEMPLATE template0; </programlisting> - In this example, the <literal>TEMPLATE template0</> clause is required if - the specified locale is different from the one in <literal>template1</>. + In this example, the <literal>TEMPLATE template0</literal> clause is required if + the specified locale is different from the one in <literal>template1</literal>. (If it is not, then specifying the locale explicitly is redundant.) </para> <para> - To create a database <literal>music2</> with a different locale and a + To create a database <literal>music2</literal> with a different locale and a different character set encoding: <programlisting> CREATE DATABASE music2 diff --git a/doc/src/sgml/ref/create_domain.sgml b/doc/src/sgml/ref/create_domain.sgml index 85ed57dd088..705ff55c49f 100644 --- a/doc/src/sgml/ref/create_domain.sgml +++ b/doc/src/sgml/ref/create_domain.sgml @@ -45,7 +45,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <para> If a schema name is given (for example, <literal>CREATE DOMAIN - myschema.mydomain ...</>) then the domain is created in the + myschema.mydomain ...</literal>) 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. @@ -95,7 +95,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <para> An optional collation for the domain. If no collation is specified, the underlying data type's default collation is used. - The underlying type must be collatable if <literal>COLLATE</> + The underlying type must be collatable if <literal>COLLATE</literal> is specified. </para> </listitem> @@ -106,7 +106,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <listitem> <para> - The <literal>DEFAULT</> clause specifies a default value for + The <literal>DEFAULT</literal> 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 @@ -136,7 +136,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea </varlistentry> <varlistentry> - <term><literal>NOT NULL</></term> + <term><literal>NOT NULL</literal></term> <listitem> <para> Values of this domain are prevented from being null @@ -146,7 +146,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea </varlistentry> <varlistentry> - <term><literal>NULL</></term> + <term><literal>NULL</literal></term> <listitem> <para> Values of this domain are allowed to be null. This is the default. @@ -163,10 +163,10 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <varlistentry> <term><literal>CHECK (<replaceable class="parameter">expression</replaceable>)</literal></term> <listitem> - <para><literal>CHECK</> clauses specify integrity constraints or tests + <para><literal>CHECK</literal> 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 <literal>VALUE</> + producing a Boolean result. It should use the key word <literal>VALUE</literal> 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 @@ -175,13 +175,13 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <para> Currently, <literal>CHECK</literal> expressions cannot contain - subqueries nor refer to variables other than <literal>VALUE</>. + subqueries nor refer to variables other than <literal>VALUE</literal>. </para> <para> When a domain has multiple <literal>CHECK</literal> constraints, they will be tested in alphabetical order by name. - (<productname>PostgreSQL</> versions before 9.5 did not honor any + (<productname>PostgreSQL</productname> versions before 9.5 did not honor any particular firing order for <literal>CHECK</literal> constraints.) </para> </listitem> @@ -193,7 +193,7 @@ CREATE DOMAIN <replaceable class="parameter">name</replaceable> [ AS ] <replacea <title>Notes</title> <para> - Domain constraints, particularly <literal>NOT NULL</>, are checked when + Domain constraints, particularly <literal>NOT NULL</literal>, 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 @@ -211,7 +211,7 @@ INSERT INTO tab (domcol) VALUES ((SELECT domcol FROM tab WHERE false)); It is very difficult to avoid such problems, because of SQL's general assumption that a null value is a valid value of every data type. Best practice therefore is to design a domain's constraints so that a null value is allowed, - and then to apply column <literal>NOT NULL</> constraints to columns of + and then to apply column <literal>NOT NULL</literal> constraints to columns of the domain type as needed, rather than directly to the domain type. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_event_trigger.sgml b/doc/src/sgml/ref/create_event_trigger.sgml index 7decfbb983c..9652f024121 100644 --- a/doc/src/sgml/ref/create_event_trigger.sgml +++ b/doc/src/sgml/ref/create_event_trigger.sgml @@ -33,7 +33,7 @@ CREATE EVENT TRIGGER <replaceable class="parameter">name</replaceable> <para> <command>CREATE EVENT TRIGGER</command> creates a new event trigger. - Whenever the designated event occurs and the <literal>WHEN</> condition + Whenever the designated event occurs and the <literal>WHEN</literal> condition associated with the trigger, if any, is satisfied, the trigger function will be executed. For a general introduction to event triggers, see <xref linkend="event-triggers">. The user who creates an event trigger @@ -85,8 +85,8 @@ CREATE EVENT TRIGGER <replaceable class="parameter">name</replaceable> <para> A list of values for the associated <replaceable class="parameter">filter_variable</replaceable> - for which the trigger should fire. For <literal>TAG</>, this means a - list of command tags (e.g. <literal>'DROP FUNCTION'</>). + for which the trigger should fire. For <literal>TAG</literal>, this means a + list of command tags (e.g. <literal>'DROP FUNCTION'</literal>). </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml index 14e910115ab..a3a7892812a 100644 --- a/doc/src/sgml/ref/create_extension.sgml +++ b/doc/src/sgml/ref/create_extension.sgml @@ -39,7 +39,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <para> Loading an extension essentially amounts to running the extension's script - file. The script will typically create new <acronym>SQL</> objects such as + file. The script will typically create new <acronym>SQL</acronym> objects such as functions, data types, operators and index support methods. <command>CREATE EXTENSION</command> additionally records the identities of all the created objects, so that they can be dropped again if @@ -62,7 +62,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if an extension with the same name already @@ -97,17 +97,17 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name </para> <para> - If the extension specifies a <literal>schema</> parameter in its + If the extension specifies a <literal>schema</literal> parameter in its control file, then that schema cannot be overridden with - a <literal>SCHEMA</> clause. Normally, an error will be raised if - a <literal>SCHEMA</> clause is given and it conflicts with the - extension's <literal>schema</> parameter. However, if - the <literal>CASCADE</> clause is also given, + a <literal>SCHEMA</literal> clause. Normally, an error will be raised if + a <literal>SCHEMA</literal> clause is given and it conflicts with the + extension's <literal>schema</literal> parameter. However, if + the <literal>CASCADE</literal> clause is also given, then <replaceable class="parameter">schema_name</replaceable> is ignored when it conflicts. The given <replaceable class="parameter">schema_name</replaceable> will be used for installation of any needed extensions that do not - specify <literal>schema</> in their control files. + specify <literal>schema</literal> in their control files. </para> <para> @@ -134,13 +134,13 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <term><replaceable class="parameter">old_version</replaceable></term> <listitem> <para> - <literal>FROM</> <replaceable class="parameter">old_version</> + <literal>FROM</literal> <replaceable class="parameter">old_version</replaceable> must be specified when, and only when, you are attempting to install - an extension that replaces an <quote>old style</> module that is just + an extension that replaces an <quote>old style</quote> module that is just a collection of objects not packaged into an extension. This option - causes <command>CREATE EXTENSION</> to run an alternative installation + causes <command>CREATE EXTENSION</command> to run an alternative installation script that absorbs the existing objects into the extension, instead - of creating new objects. Be careful that <literal>SCHEMA</> specifies + of creating new objects. Be careful that <literal>SCHEMA</literal> specifies the schema containing these pre-existing objects. </para> @@ -150,7 +150,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name extension's author, and might vary if there is more than one version of the old-style module that can be upgraded into an extension. For the standard additional modules supplied with pre-9.1 - <productname>PostgreSQL</productname>, use <literal>unpackaged</> + <productname>PostgreSQL</productname>, use <literal>unpackaged</literal> for <replaceable class="parameter">old_version</replaceable> when updating a module to extension style. </para> @@ -158,12 +158,12 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name </varlistentry> <varlistentry> - <term><literal>CASCADE</></term> + <term><literal>CASCADE</literal></term> <listitem> <para> Automatically install any extensions that this extension depends on that are not already installed. Their dependencies are likewise - automatically installed, recursively. The <literal>SCHEMA</> clause, + automatically installed, recursively. The <literal>SCHEMA</literal> 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 @@ -178,7 +178,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name <title>Notes</title> <para> - Before you can use <command>CREATE EXTENSION</> to load an extension + Before you can use <command>CREATE EXTENSION</command> to load an extension into a database, the extension's supporting files must be installed. Information about installing the extensions supplied with <productname>PostgreSQL</productname> can be found in @@ -211,13 +211,13 @@ CREATE EXTENSION hstore; </para> <para> - Update a pre-9.1 installation of <literal>hstore</> into + Update a pre-9.1 installation of <literal>hstore</literal> into extension style: <programlisting> CREATE EXTENSION hstore SCHEMA public FROM unpackaged; </programlisting> Be careful to specify the schema in which you installed the existing - <literal>hstore</> objects. + <literal>hstore</literal> objects. </para> </refsect1> @@ -225,7 +225,7 @@ CREATE EXTENSION hstore SCHEMA public FROM unpackaged; <title>Compatibility</title> <para> - <command>CREATE EXTENSION</command> is a <productname>PostgreSQL</> + <command>CREATE EXTENSION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml index 1161e05d1c6..87403a55e3b 100644 --- a/doc/src/sgml/ref/create_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/create_foreign_data_wrapper.sgml @@ -117,7 +117,7 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <productname>PostgreSQL</>'s foreign-data functionality is still under + <productname>PostgreSQL</productname>'s 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. @@ -128,22 +128,22 @@ CREATE FOREIGN DATA WRAPPER <replaceable class="parameter">name</replaceable> <title>Examples</title> <para> - Create a useless foreign-data wrapper <literal>dummy</>: + Create a useless foreign-data wrapper <literal>dummy</literal>: <programlisting> CREATE FOREIGN DATA WRAPPER dummy; </programlisting> </para> <para> - Create a foreign-data wrapper <literal>file</> with - handler function <literal>file_fdw_handler</>: + Create a foreign-data wrapper <literal>file</literal> with + handler function <literal>file_fdw_handler</literal>: <programlisting> CREATE FOREIGN DATA WRAPPER file HANDLER file_fdw_handler; </programlisting> </para> <para> - Create a foreign-data wrapper <literal>mywrapper</> with some + Create a foreign-data wrapper <literal>mywrapper</literal> with some options: <programlisting> CREATE FOREIGN DATA WRAPPER mywrapper @@ -159,7 +159,7 @@ CREATE FOREIGN DATA WRAPPER mywrapper 9075-9 (SQL/MED), with the exception that the <literal>HANDLER</literal> and <literal>VALIDATOR</literal> clauses are extensions and the standard clauses <literal>LIBRARY</literal> and <literal>LANGUAGE</literal> - are not implemented in <productname>PostgreSQL</>. + are not implemented in <productname>PostgreSQL</productname>. </para> <para> diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml index f514b2d59f3..47705fd187e 100644 --- a/doc/src/sgml/ref/create_foreign_table.sgml +++ b/doc/src/sgml/ref/create_foreign_table.sgml @@ -62,7 +62,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <para> If a schema name is given (for example, <literal>CREATE FOREIGN TABLE - myschema.mytable ...</>) then the table is created in the specified + myschema.mytable ...</literal>) 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 foreign table, table, sequence, index, @@ -95,7 +95,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a relation with the same name already exists. @@ -140,7 +140,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <term><literal>COLLATE <replaceable>collation</replaceable></literal></term> <listitem> <para> - The <literal>COLLATE</> clause assigns a collation to + The <literal>COLLATE</literal> clause assigns a collation to the column (which must be of a collatable data type). If not specified, the column data type's default collation is used. </para> @@ -151,7 +151,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term> <listitem> <para> - The optional <literal>INHERITS</> clause specifies a list of + The optional <literal>INHERITS</literal> 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 @@ -166,7 +166,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <para> 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 <literal>col must be positive</> can be used + so constraint names like <literal>col must be positive</literal> 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. @@ -175,7 +175,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </varlistentry> <varlistentry> - <term><literal>NOT NULL</></term> + <term><literal>NOT NULL</literal></term> <listitem> <para> The column is not allowed to contain null values. @@ -184,7 +184,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </varlistentry> <varlistentry> - <term><literal>NULL</></term> + <term><literal>NULL</literal></term> <listitem> <para> The column is allowed to contain null values. This is the default. @@ -202,7 +202,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <term><literal>CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </literal></term> <listitem> <para> - The <literal>CHECK</> clause specifies an expression producing a + The <literal>CHECK</literal> 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. @@ -219,7 +219,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </para> <para> - A constraint marked with <literal>NO INHERIT</> will not propagate to + A constraint marked with <literal>NO INHERIT</literal> will not propagate to child tables. </para> </listitem> @@ -230,7 +230,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <replaceable>default_expr</replaceable></literal></term> <listitem> <para> - The <literal>DEFAULT</> clause assigns a default data value for + The <literal>DEFAULT</literal> 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 @@ -279,9 +279,9 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <title>Notes</title> <para> - Constraints on foreign tables (such as <literal>CHECK</> - or <literal>NOT NULL</> clauses) are not enforced by the - core <productname>PostgreSQL</> system, and most foreign data wrappers + Constraints on foreign tables (such as <literal>CHECK</literal> + or <literal>NOT NULL</literal> clauses) are not enforced by the + core <productname>PostgreSQL</productname> 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 @@ -300,7 +300,7 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </para> <para> - Although <productname>PostgreSQL</> does not attempt to enforce + Although <productname>PostgreSQL</productname> 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 @@ -314,8 +314,8 @@ CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] <title>Examples</title> <para> - Create foreign table <structname>films</>, which will be accessed through - the server <structname>film_server</>: + Create foreign table <structname>films</structname>, which will be accessed through + the server <structname>film_server</structname>: <programlisting> CREATE FOREIGN TABLE films ( @@ -330,9 +330,9 @@ SERVER film_server; </programlisting></para> <para> - Create foreign table <structname>measurement_y2016m07</>, which will be - accessed through the server <structname>server_07</>, as a partition - of the range partitioned table <structname>measurement</>: + Create foreign table <structname>measurement_y2016m07</structname>, which will be + accessed through the server <structname>server_07</structname>, as a partition + of the range partitioned table <structname>measurement</structname>: <programlisting> CREATE FOREIGN TABLE measurement_y2016m07 @@ -348,10 +348,10 @@ CREATE FOREIGN TABLE measurement_y2016m07 <para> The <command>CREATE FOREIGN TABLE</command> command largely conforms to the <acronym>SQL</acronym> standard; however, much as with - <link linkend="sql-createtable"><command>CREATE TABLE</></link>, - <literal>NULL</> constraints and zero-column foreign tables are permitted. + <link linkend="sql-createtable"><command>CREATE TABLE</command></link>, + <literal>NULL</literal> constraints and zero-column foreign tables are permitted. The ability to specify column default values is also - a <productname>PostgreSQL</> extension. Table inheritance, in the form + a <productname>PostgreSQL</productname> extension. Table inheritance, in the form defined by <productname>PostgreSQL</productname>, is nonstandard. </para> diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml index 072e033687b..97cb9b7fc8a 100644 --- a/doc/src/sgml/ref/create_function.sgml +++ b/doc/src/sgml/ref/create_function.sgml @@ -58,7 +58,7 @@ CREATE [ OR REPLACE ] FUNCTION The name of the new function must not match any existing function with the same input argument types in the same schema. However, functions of different argument types can share a name (this is - called <firstterm>overloading</>). + called <firstterm>overloading</firstterm>). </para> <para> @@ -68,13 +68,13 @@ CREATE [ OR REPLACE ] FUNCTION tried, you would actually be creating a new, distinct function). Also, <command>CREATE OR REPLACE FUNCTION</command> will not let you change the return type of an existing function. To do that, - you must drop and recreate the function. (When using <literal>OUT</> + you must drop and recreate the function. (When using <literal>OUT</literal> parameters, that means you cannot change the types of any - <literal>OUT</> parameters except by dropping the function.) + <literal>OUT</literal> parameters except by dropping the function.) </para> <para> - When <command>CREATE OR REPLACE FUNCTION</> is used to replace an + When <command>CREATE OR REPLACE FUNCTION</command> 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 @@ -87,7 +87,7 @@ CREATE [ OR REPLACE ] FUNCTION triggers, etc. that refer to the old function. Use <command>CREATE OR REPLACE FUNCTION</command> to change a function definition without breaking objects that refer to the function. - Also, <command>ALTER FUNCTION</> can be used to change most of the + Also, <command>ALTER FUNCTION</command> can be used to change most of the auxiliary properties of an existing function. </para> @@ -121,12 +121,12 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para> - The mode of an argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. - Only <literal>OUT</> arguments can follow a <literal>VARIADIC</> one. - Also, <literal>OUT</> and <literal>INOUT</> arguments cannot be used - together with the <literal>RETURNS TABLE</> notation. + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. + Only <literal>OUT</literal> arguments can follow a <literal>VARIADIC</literal> one. + Also, <literal>OUT</literal> and <literal>INOUT</literal> arguments cannot be used + together with the <literal>RETURNS TABLE</literal> notation. </para> </listitem> </varlistentry> @@ -160,7 +160,7 @@ CREATE [ OR REPLACE ] FUNCTION </para> <para> Depending on the implementation language it might also be allowed - to specify <quote>pseudo-types</> such as <type>cstring</>. + to specify <quote>pseudo-types</quote> such as <type>cstring</type>. Pseudo-types indicate that the actual argument type is either incompletely specified, or outside the set of ordinary SQL data types. </para> @@ -183,7 +183,7 @@ CREATE [ OR REPLACE ] FUNCTION 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 <literal>INOUT</>) parameters can have a default + Only input (including <literal>INOUT</literal>) parameters can have a default value. All input parameters following a parameter with a default value must have default values as well. </para> @@ -199,15 +199,15 @@ CREATE [ OR REPLACE ] FUNCTION 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 <quote>pseudo-types</> such as <type>cstring</>. + to specify <quote>pseudo-types</quote> such as <type>cstring</type>. If the function is not supposed to return a value, specify - <type>void</> as the return type. + <type>void</type> as the return type. </para> <para> - When there are <literal>OUT</> or <literal>INOUT</> parameters, - the <literal>RETURNS</> clause can be omitted. If present, it + When there are <literal>OUT</literal> or <literal>INOUT</literal> parameters, + the <literal>RETURNS</literal> clause can be omitted. If present, it must agree with the result type implied by the output parameters: - <literal>RECORD</> if there are multiple output parameters, or + <literal>RECORD</literal> if there are multiple output parameters, or the same type as the single output parameter. </para> <para> @@ -229,10 +229,10 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para> - The name of an output column in the <literal>RETURNS TABLE</> + The name of an output column in the <literal>RETURNS TABLE</literal> syntax. This is effectively another way of declaring a named - <literal>OUT</> parameter, except that <literal>RETURNS TABLE</> - also implies <literal>RETURNS SETOF</>. + <literal>OUT</literal> parameter, except that <literal>RETURNS TABLE</literal> + also implies <literal>RETURNS SETOF</literal>. </para> </listitem> </varlistentry> @@ -242,7 +242,7 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para> - The data type of an output column in the <literal>RETURNS TABLE</> + The data type of an output column in the <literal>RETURNS TABLE</literal> syntax. </para> </listitem> @@ -284,9 +284,9 @@ CREATE [ OR REPLACE ] FUNCTION <listitem> <para><literal>WINDOW</literal> indicates that the function is a - <firstterm>window function</> rather than a plain function. + <firstterm>window function</firstterm> rather than a plain function. This is currently only useful for functions written in C. - The <literal>WINDOW</> attribute cannot be changed when + The <literal>WINDOW</literal> attribute cannot be changed when replacing an existing function definition. </para> </listitem> @@ -321,20 +321,20 @@ CREATE [ OR REPLACE ] FUNCTION 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 <literal>AFTER</> triggers that wish to + inappropriate for <literal>AFTER</literal> triggers that wish to query rows modified by the current command.) Also note - that the <function>current_timestamp</> family of functions qualify + that the <function>current_timestamp</function> family of functions qualify as stable, since their values do not change within a transaction. </para> <para><literal>VOLATILE</literal> 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 <literal>random()</>, <literal>currval()</>, - <literal>timeofday()</>. But note that any function that has + some examples are <literal>random()</literal>, <literal>currval()</literal>, + <literal>timeofday()</literal>. 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 - <literal>setval()</>. + <literal>setval()</literal>. </para> <para> @@ -430,11 +430,11 @@ CREATE [ OR REPLACE ] FUNCTION 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. <literal>setval</>). They should + persistent changes to settings (e.g. <literal>setval</literal>). 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. <literal>setseed</> cannot be executed other than by the group + (e.g. <literal>setseed</literal> 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 @@ -443,7 +443,7 @@ CREATE [ OR REPLACE ] FUNCTION 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 <literal>UNSAFE</>, which is + If in doubt, functions should be labeled as <literal>UNSAFE</literal>, which is the default. </para> </listitem> @@ -483,23 +483,23 @@ CREATE [ OR REPLACE ] FUNCTION <term><replaceable>value</replaceable></term> <listitem> <para> - The <literal>SET</> clause causes the specified configuration + The <literal>SET</literal> 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. - <literal>SET FROM CURRENT</> saves the value of the parameter that - is current when <command>CREATE FUNCTION</> is executed as the value + <literal>SET FROM CURRENT</literal> saves the value of the parameter that + is current when <command>CREATE FUNCTION</command> is executed as the value to be applied when the function is entered. </para> <para> - If a <literal>SET</> clause is attached to a function, then - the effects of a <command>SET LOCAL</> command executed inside the + If a <literal>SET</literal> clause is attached to a function, then + the effects of a <command>SET LOCAL</command> command executed inside the function for the same variable are restricted to the function: the configuration parameter's prior value is still restored at function exit. However, an ordinary - <command>SET</> command (without <literal>LOCAL</>) overrides the - <literal>SET</> clause, much as it would do for a previous <command>SET - LOCAL</> command: the effects of such a command will persist after + <command>SET</command> command (without <literal>LOCAL</literal>) overrides the + <literal>SET</literal> clause, much as it would do for a previous <command>SET + LOCAL</command> command: the effects of such a command will persist after function exit, unless the current transaction is rolled back. </para> @@ -570,7 +570,7 @@ CREATE [ OR REPLACE ] FUNCTION <variablelist> <varlistentry> - <term><literal>isStrict</></term> + <term><literal>isStrict</literal></term> <listitem> <para> Equivalent to <literal>STRICT</literal> or <literal>RETURNS NULL ON NULL INPUT</literal>. @@ -579,7 +579,7 @@ CREATE [ OR REPLACE ] FUNCTION </varlistentry> <varlistentry> - <term><literal>isCachable</></term> + <term><literal>isCachable</literal></term> <listitem> <para><literal>isCachable</literal> is an obsolete equivalent of <literal>IMMUTABLE</literal>; it's still accepted for @@ -619,7 +619,7 @@ CREATE [ OR REPLACE ] FUNCTION <para> Two functions are considered the same if they have the same names and - <emphasis>input</> argument types, ignoring any <literal>OUT</> + <emphasis>input</emphasis> argument types, ignoring any <literal>OUT</literal> parameters. Thus for example these declarations conflict: <programlisting> CREATE FUNCTION foo(int) ... @@ -635,7 +635,7 @@ CREATE FUNCTION foo(int, out text) ... CREATE FUNCTION foo(int) ... CREATE FUNCTION foo(int, int default 42) ... </programlisting> - A call <literal>foo(10)</> will fail due to the ambiguity about which + A call <literal>foo(10)</literal> will fail due to the ambiguity about which function should be called. </para> @@ -648,16 +648,16 @@ CREATE FUNCTION foo(int, int default 42) ... The full <acronym>SQL</acronym> type syntax is allowed for declaring a function's arguments and return value. However, parenthesized type modifiers (e.g., the precision field for - type <type>numeric</type>) are discarded by <command>CREATE FUNCTION</>. + type <type>numeric</type>) are discarded by <command>CREATE FUNCTION</command>. Thus for example - <literal>CREATE FUNCTION foo (varchar(10)) ...</> + <literal>CREATE FUNCTION foo (varchar(10)) ...</literal> is exactly the same as - <literal>CREATE FUNCTION foo (varchar) ...</>. + <literal>CREATE FUNCTION foo (varchar) ...</literal>. </para> <para> When replacing an existing function with <command>CREATE OR REPLACE - FUNCTION</>, there are restrictions on changing parameter names. + FUNCTION</command>, 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 @@ -668,9 +668,9 @@ CREATE FUNCTION foo(int, int default 42) ... </para> <para> - If a function is declared <literal>STRICT</> with a <literal>VARIADIC</> + If a function is declared <literal>STRICT</literal> with a <literal>VARIADIC</literal> argument, the strictness check tests that the variadic array <emphasis>as - a whole</> is non-null. The function will still be called if the + a whole</emphasis> is non-null. The function will still be called if the array has null elements. </para> @@ -723,7 +723,7 @@ CREATE FUNCTION dup(int) RETURNS dup_result SELECT * FROM dup(42); </programlisting> - Another way to return multiple columns is to use a <literal>TABLE</> + Another way to return multiple columns is to use a <literal>TABLE</literal> function: <programlisting> CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) @@ -732,8 +732,8 @@ CREATE FUNCTION dup(int) RETURNS TABLE(f1 int, f2 text) SELECT * FROM dup(42); </programlisting> - However, a <literal>TABLE</> function is different from the - preceding examples, because it actually returns a <emphasis>set</> + However, a <literal>TABLE</literal> function is different from the + preceding examples, because it actually returns a <emphasis>set</emphasis> of records, not just one record. </para> </refsect1> @@ -742,8 +742,8 @@ SELECT * FROM dup(42); <title>Writing <literal>SECURITY DEFINER</literal> Functions Safely</title> <indexterm> - <primary><varname>search_path</varname> configuration parameter</> - <secondary>use in securing functions</> + <primary><varname>search_path</varname> configuration parameter</primary> + <secondary>use in securing functions</secondary> </indexterm> <para> @@ -758,7 +758,7 @@ SELECT * FROM dup(42); 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 <literal>pg_temp</><indexterm><primary>pg_temp</><secondary>securing functions</></> as the last entry in <varname>search_path</>. + write <literal>pg_temp</literal><indexterm><primary>pg_temp</primary><secondary>securing functions</secondary></indexterm> as the last entry in <varname>search_path</varname>. This function illustrates safe usage: <programlisting> @@ -778,27 +778,27 @@ $$ LANGUAGE plpgsql SET search_path = admin, pg_temp; </programlisting> - This function's intention is to access a table <literal>admin.pwds</>. - But without the <literal>SET</> clause, or with a <literal>SET</> clause - mentioning only <literal>admin</>, the function could be subverted by - creating a temporary table named <literal>pwds</>. + This function's intention is to access a table <literal>admin.pwds</literal>. + But without the <literal>SET</literal> clause, or with a <literal>SET</literal> clause + mentioning only <literal>admin</literal>, the function could be subverted by + creating a temporary table named <literal>pwds</literal>. </para> <para> Before <productname>PostgreSQL</productname> version 8.3, the - <literal>SET</> clause was not available, and so older functions may + <literal>SET</literal> clause was not available, and so older functions may contain rather complicated logic to save, set, and restore - <varname>search_path</>. The <literal>SET</> clause is far easier + <varname>search_path</varname>. The <literal>SET</literal> clause is far easier to use for this purpose. </para> <para> Another point to keep in mind is that by default, execute privilege - is granted to <literal>PUBLIC</> for newly created functions + is granted to <literal>PUBLIC</literal> for newly created functions (see <xref linkend="sql-grant"> 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 <literal>PUBLIC</> privileges and then grant execute + the default <literal>PUBLIC</literal> 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: diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index a462be790f6..bb2601dc8c8 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -51,8 +51,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= 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 - <literal>upper(col)</> would allow the clause - <literal>WHERE upper(col) = 'JIM'</> to use an index. + <literal>upper(col)</literal> would allow the clause + <literal>WHERE upper(col) = 'JIM'</literal> to use an index. </para> <para> @@ -85,7 +85,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> All functions and operators used in an index definition must be - <quote>immutable</>, that is, their results must depend only on + <quote>immutable</quote>, 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 @@ -115,7 +115,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <term><literal>CONCURRENTLY</literal></term> <listitem> <para> - When this option is used, <productname>PostgreSQL</> will build the + When this option is used, <productname>PostgreSQL</productname> 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's done. @@ -144,7 +144,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> 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. If the name is omitted, <productname>PostgreSQL</> chooses a + table. If the name is omitted, <productname>PostgreSQL</productname> chooses a suitable name based on the parent table's name and the indexed column name(s). </para> @@ -166,8 +166,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> The name of the index method to be used. Choices are <literal>btree</literal>, <literal>hash</literal>, - <literal>gist</literal>, <literal>spgist</>, <literal>gin</>, and - <literal>brin</>. + <literal>gist</literal>, <literal>spgist</literal>, <literal>gin</literal>, and + <literal>brin</literal>. The default method is <literal>btree</literal>. </para> </listitem> @@ -217,7 +217,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </varlistentry> <varlistentry> - <term><literal>ASC</></term> + <term><literal>ASC</literal></term> <listitem> <para> Specifies ascending sort order (which is the default). @@ -226,7 +226,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </varlistentry> <varlistentry> - <term><literal>DESC</></term> + <term><literal>DESC</literal></term> <listitem> <para> Specifies descending sort order. @@ -235,21 +235,21 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </varlistentry> <varlistentry> - <term><literal>NULLS FIRST</></term> + <term><literal>NULLS FIRST</literal></term> <listitem> <para> Specifies that nulls sort before non-nulls. This is the default - when <literal>DESC</> is specified. + when <literal>DESC</literal> is specified. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>NULLS LAST</></term> + <term><literal>NULLS LAST</literal></term> <listitem> <para> Specifies that nulls sort after non-nulls. This is the default - when <literal>DESC</> is not specified. + when <literal>DESC</literal> is not specified. </para> </listitem> </varlistentry> @@ -292,15 +292,15 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <title id="SQL-CREATEINDEX-storage-parameters-title">Index Storage Parameters</title> <para> - The optional <literal>WITH</> clause specifies <firstterm>storage - parameters</> for the index. Each index method has its own set of allowed + The optional <literal>WITH</literal> clause specifies <firstterm>storage + parameters</firstterm> 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: </para> <variablelist> <varlistentry> - <term><literal>fillfactor</></term> + <term><literal>fillfactor</literal></term> <listitem> <para> The fillfactor for an index is a percentage that determines how full @@ -327,14 +327,14 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <variablelist> <varlistentry> - <term><literal>buffering</></term> + <term><literal>buffering</literal></term> <listitem> <para> Determines whether the buffering build technique described in <xref linkend="gist-buffering-build"> is used to build the index. With - <literal>OFF</> it is disabled, with <literal>ON</> it is enabled, and - with <literal>AUTO</> it is initially disabled, but turned on - on-the-fly once the index size reaches <xref linkend="guc-effective-cache-size">. The default is <literal>AUTO</>. + <literal>OFF</literal> it is disabled, with <literal>ON</literal> it is enabled, and + with <literal>AUTO</literal> it is initially disabled, but turned on + on-the-fly once the index size reaches <xref linkend="guc-effective-cache-size">. The default is <literal>AUTO</literal>. </para> </listitem> </varlistentry> @@ -346,23 +346,23 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <variablelist> <varlistentry> - <term><literal>fastupdate</></term> + <term><literal>fastupdate</literal></term> <listitem> <para> This setting controls usage of the fast update technique described in <xref linkend="gin-fast-update">. It is a Boolean parameter: - <literal>ON</> enables fast update, <literal>OFF</> disables it. - (Alternative spellings of <literal>ON</> and <literal>OFF</> are + <literal>ON</literal> enables fast update, <literal>OFF</literal> disables it. + (Alternative spellings of <literal>ON</literal> and <literal>OFF</literal> are allowed as described in <xref linkend="config-setting">.) The - default is <literal>ON</>. + default is <literal>ON</literal>. </para> <note> <para> - Turning <literal>fastupdate</> off via <command>ALTER INDEX</> prevents + Turning <literal>fastupdate</literal> off via <command>ALTER INDEX</command> prevents future insertions from going into the list of pending index entries, but does not in itself flush previous entries. You might want to - <command>VACUUM</> the table or call <function>gin_clean_pending_list</> + <command>VACUUM</command> the table or call <function>gin_clean_pending_list</function> function afterward to ensure the pending list is emptied. </para> </note> @@ -371,7 +371,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </variablelist> <variablelist> <varlistentry> - <term><literal>gin_pending_list_limit</></term> + <term><literal>gin_pending_list_limit</literal></term> <listitem> <para> Custom <xref linkend="guc-gin-pending-list-limit"> parameter. @@ -382,23 +382,23 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </variablelist> <para> - <acronym>BRIN</> indexes accept different parameters: + <acronym>BRIN</acronym> indexes accept different parameters: </para> <variablelist> <varlistentry> - <term><literal>pages_per_range</></term> + <term><literal>pages_per_range</literal></term> <listitem> <para> Defines the number of table blocks that make up one block range for - each entry of a <acronym>BRIN</> index (see <xref linkend="brin-intro"> - for more details). The default is <literal>128</>. + each entry of a <acronym>BRIN</acronym> index (see <xref linkend="brin-intro"> + for more details). The default is <literal>128</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>autosummarize</></term> + <term><literal>autosummarize</literal></term> <listitem> <para> Defines whether a summarization run is invoked for the previous page @@ -419,7 +419,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> Creating an index can interfere with regular operation of a database. - Normally <productname>PostgreSQL</> locks the table to be indexed against + Normally <productname>PostgreSQL</productname> 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 @@ -430,11 +430,11 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= </para> <para> - <productname>PostgreSQL</> supports building indexes without locking + <productname>PostgreSQL</productname> supports building indexes without locking out writes. This method is invoked by specifying the - <literal>CONCURRENTLY</> option of <command>CREATE INDEX</>. + <literal>CONCURRENTLY</literal> option of <command>CREATE INDEX</command>. When this option is used, - <productname>PostgreSQL</> must perform two scans of the table, and in + <productname>PostgreSQL</productname> 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 @@ -452,7 +452,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= After the second scan, the index build must wait for any transactions that have a snapshot (see <xref linkend="mvcc">) predating the second scan to terminate. Then finally the index can be marked ready for use, - and the <command>CREATE INDEX</> command terminates. + and the <command>CREATE INDEX</command> 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. @@ -460,11 +460,11 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class= <para> If a problem arises while scanning the table, such as a deadlock or a - uniqueness violation in a unique index, the <command>CREATE INDEX</> - command will fail but leave behind an <quote>invalid</> index. This index + uniqueness violation in a unique index, the <command>CREATE INDEX</command> + command will fail but leave behind an <quote>invalid</quote> index. This index will be ignored for querying purposes because it might be incomplete; - however it will still consume update overhead. The <application>psql</> - <command>\d</> command will report such an index as <literal>INVALID</>: + however it will still consume update overhead. The <application>psql</application> + <command>\d</command> command will report such an index as <literal>INVALID</literal>: <programlisting> postgres=# \d tab @@ -478,8 +478,8 @@ Indexes: The recommended recovery method in such cases is to drop the index and try again to perform - <command>CREATE INDEX CONCURRENTLY</>. (Another possibility is to rebuild - the index with <command>REINDEX</>. However, since <command>REINDEX</> + <command>CREATE INDEX CONCURRENTLY</command>. (Another possibility is to rebuild + the index with <command>REINDEX</command>. However, since <command>REINDEX</command> does not support concurrent builds, this option is unlikely to seem attractive.) </para> @@ -490,7 +490,7 @@ Indexes: 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 <quote>invalid</> index + if a failure does occur in the second scan, the <quote>invalid</quote> index continues to enforce its uniqueness constraint afterwards. </para> @@ -505,8 +505,8 @@ Indexes: same table to occur in parallel, 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 <command>CREATE INDEX</> command can be performed within - a transaction block, but <command>CREATE INDEX CONCURRENTLY</> cannot. + is that a regular <command>CREATE INDEX</command> command can be performed within + a transaction block, but <command>CREATE INDEX CONCURRENTLY</command> cannot. </para> </refsect2> </refsect1> @@ -547,17 +547,17 @@ Indexes: <para> For index methods that support ordered scans (currently, only B-tree), - the optional clauses <literal>ASC</>, <literal>DESC</>, <literal>NULLS - FIRST</>, and/or <literal>NULLS LAST</> can be specified to modify + the optional clauses <literal>ASC</literal>, <literal>DESC</literal>, <literal>NULLS + FIRST</literal>, and/or <literal>NULLS LAST</literal> 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 <literal>DESC</> index — that sort ordering is already + single-column <literal>DESC</literal> index — 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 <literal>SELECT ... ORDER BY x ASC, y - DESC</>. The <literal>NULLS</> options are useful if you need to support - <quote>nulls sort low</> behavior, rather than the default <quote>nulls - sort high</>, in queries that depend on indexes to avoid sorting steps. + DESC</literal>. The <literal>NULLS</literal> options are useful if you need to support + <quote>nulls sort low</quote> behavior, rather than the default <quote>nulls + sort high</quote>, in queries that depend on indexes to avoid sorting steps. </para> <para> @@ -577,8 +577,8 @@ Indexes: Prior releases of <productname>PostgreSQL</productname> also had an R-tree index method. This method has been removed because it had no significant advantages over the GiST method. - If <literal>USING rtree</> is specified, <command>CREATE INDEX</> - will interpret it as <literal>USING gist</>, to simplify conversion + If <literal>USING rtree</literal> is specified, <command>CREATE INDEX</command> + will interpret it as <literal>USING gist</literal>, to simplify conversion of old databases to GiST. </para> </refsect1> @@ -595,13 +595,13 @@ CREATE UNIQUE INDEX title_idx ON films (title); </para> <para> - To create an index on the expression <literal>lower(title)</>, + To create an index on the expression <literal>lower(title)</literal>, allowing efficient case-insensitive searches: <programlisting> CREATE INDEX ON films ((lower(title))); </programlisting> (In this example we have chosen to omit the index name, so the system - will choose a name, typically <literal>films_lower_idx</>.) + will choose a name, typically <literal>films_lower_idx</literal>.) </para> <para> @@ -626,16 +626,16 @@ CREATE UNIQUE INDEX title_idx ON films (title) WITH (fillfactor = 70); </para> <para> - To create a <acronym>GIN</> index with fast updates disabled: + To create a <acronym>GIN</acronym> index with fast updates disabled: <programlisting> CREATE INDEX gin_idx ON documents_table USING GIN (locations) WITH (fastupdate = off); </programlisting> </para> <para> - To create an index on the column <literal>code</> in the table - <literal>films</> and have the index reside in the tablespace - <literal>indexspace</>: + To create an index on the column <literal>code</literal> in the table + <literal>films</literal> and have the index reside in the tablespace + <literal>indexspace</literal>: <programlisting> CREATE INDEX code_idx ON films (code) TABLESPACE indexspace; </programlisting> diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml index 75165b677f1..20d56a766f3 100644 --- a/doc/src/sgml/ref/create_language.sgml +++ b/doc/src/sgml/ref/create_language.sgml @@ -40,14 +40,14 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <note> <para> As of <productname>PostgreSQL</productname> 9.1, most procedural - languages have been made into <quote>extensions</>, and should + languages have been made into <quote>extensions</quote>, and should therefore be installed with <xref linkend="sql-createextension"> not <command>CREATE LANGUAGE</command>. Direct use of <command>CREATE LANGUAGE</command> should now be confined to - extension installation scripts. If you have a <quote>bare</> + extension installation scripts. If you have a <quote>bare</quote> language in your database, perhaps as a result of an upgrade, you can convert it to an extension using - <literal>CREATE EXTENSION <replaceable>langname</> FROM + <literal>CREATE EXTENSION <replaceable>langname</replaceable> FROM unpackaged</literal>. </para> </note> @@ -67,11 +67,11 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa system catalog to determine the correct parameters. In the second form, the user supplies the language parameters along with the language name. The second form can be used to create a language that is not defined in - <structname>pg_pltemplate</>, but this approach is considered obsolescent. + <structname>pg_pltemplate</structname>, but this approach is considered obsolescent. </para> <para> - When the server finds an entry in the <structname>pg_pltemplate</> catalog + When the server finds an entry in the <structname>pg_pltemplate</structname> catalog for the given language name, it will use the catalog data even if the command includes language parameters. This behavior simplifies loading of old dump files, which are likely to contain out-of-date information @@ -84,7 +84,7 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa register a new language. However, the owner of a database can register a new language within that database if the language is listed in the <structname>pg_pltemplate</structname> catalog and is marked - as allowed to be created by database owners (<structfield>tmpldbacreate</> + as allowed to be created by database owners (<structfield>tmpldbacreate</structfield> is true). The default is that trusted languages can be created by database owners, but this can be adjusted by superusers by modifying the contents of <structname>pg_pltemplate</structname>. @@ -101,9 +101,9 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa and any existing functions written in the language are assumed to still be valid. In addition to the normal privilege requirements for creating a language, the user must be superuser or owner of the existing language. - The <literal>REPLACE</> case is mainly meant to be used to + The <literal>REPLACE</literal> case is mainly meant to be used to ensure that the language exists. If the language has a - <structname>pg_pltemplate</structname> entry then <literal>REPLACE</> + <structname>pg_pltemplate</structname> entry then <literal>REPLACE</literal> will not actually change anything about an existing definition, except in the unusual case where the <structname>pg_pltemplate</structname> entry has been modified since the language was created. @@ -184,9 +184,9 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa function is specified, the language does not support anonymous code blocks. The handler function must take one argument of - type <type>internal</type>, which will be the <command>DO</> command's + type <type>internal</type>, which will be the <command>DO</command> command's internal representation, and it will typically return - <type>void</>. The return value of the handler is ignored. + <type>void</type>. The return value of the handler is ignored. </para> </listitem> </varlistentry> @@ -204,7 +204,7 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa be checked when it is created. The validator function must take one argument of type <type>oid</type>, which will be the OID of the - to-be-created function, and will typically return <type>void</>. + to-be-created function, and will typically return <type>void</type>. </para> <para> @@ -220,9 +220,9 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa </variablelist> <para> - The <literal>TRUSTED</> option and the support function name(s) are + The <literal>TRUSTED</literal> option and the support function name(s) are ignored if the server has an entry for the specified language - name in <structname>pg_pltemplate</>. + name in <structname>pg_pltemplate</structname>. </para> </refsect1> @@ -243,7 +243,7 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <para> To create functions in a procedural language, a user must have the <literal>USAGE</literal> privilege for the language. By default, - <literal>USAGE</> is granted to <literal>PUBLIC</> (i.e., everyone) + <literal>USAGE</literal> is granted to <literal>PUBLIC</literal> (i.e., everyone) for trusted languages. This can be revoked if desired. </para> @@ -258,10 +258,10 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa The call handler function, the inline handler function (if any), and the validator function (if any) must already exist if the server does not have an entry for the language - in <structname>pg_pltemplate</>. But when there is an entry, + in <structname>pg_pltemplate</structname>. But when there is an entry, the functions need not already exist; they will be automatically defined if not present in the database. - (This might result in <command>CREATE LANGUAGE</> failing, if the + (This might result in <command>CREATE LANGUAGE</command> failing, if the shared library that implements the language is not available in the installation.) </para> @@ -269,11 +269,11 @@ CREATE [ OR REPLACE ] [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="pa <para> In <productname>PostgreSQL</productname> versions before 7.3, it was necessary to declare handler functions as returning the placeholder - type <type>opaque</>, rather than <type>language_handler</>. + type <type>opaque</type>, rather than <type>language_handler</type>. To support loading - of old dump files, <command>CREATE LANGUAGE</> will accept a function - declared as returning <type>opaque</>, but it will issue a notice and - change the function's declared return type to <type>language_handler</>. + of old dump files, <command>CREATE LANGUAGE</command> will accept a function + declared as returning <type>opaque</type>, but it will issue a notice and + change the function's declared return type to <type>language_handler</type>. </para> </refsect1> @@ -289,7 +289,7 @@ CREATE LANGUAGE plperl; </para> <para> - For a language not known in the <structname>pg_pltemplate</> catalog, a + For a language not known in the <structname>pg_pltemplate</structname> catalog, a sequence such as this is needed: <programlisting> CREATE FUNCTION plsample_call_handler() RETURNS language_handler diff --git a/doc/src/sgml/ref/create_materialized_view.sgml b/doc/src/sgml/ref/create_materialized_view.sgml index 577893fe929..126aa5666f8 100644 --- a/doc/src/sgml/ref/create_materialized_view.sgml +++ b/doc/src/sgml/ref/create_materialized_view.sgml @@ -36,13 +36,13 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable> <para> <command>CREATE MATERIALIZED VIEW</command> 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 <command>WITH NO DATA</> is used) and may be + the command is issued (unless <command>WITH NO DATA</command> is used) and may be refreshed later using <command>REFRESH MATERIALIZED VIEW</command>. </para> <para> <command>CREATE MATERIALIZED VIEW</command> is similar to - <command>CREATE TABLE AS</>, except that it also remembers the query used + <command>CREATE TABLE AS</command>, 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 or automatic generation of @@ -55,7 +55,7 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable> <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a materialized view with the same name already @@ -125,13 +125,13 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable> </varlistentry> <varlistentry> - <term><literal>WITH [ NO ] DATA</></term> + <term><literal>WITH [ NO ] DATA</literal></term> <listitem> <para> 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 <command>REFRESH - MATERIALIZED VIEW</> is used. + MATERIALIZED VIEW</command> is used. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/create_opclass.sgml b/doc/src/sgml/ref/create_opclass.sgml index 829d8f2fffb..08eb7f2a083 100644 --- a/doc/src/sgml/ref/create_opclass.sgml +++ b/doc/src/sgml/ref/create_opclass.sgml @@ -37,7 +37,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <command>CREATE OPERATOR CLASS</command> 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 <quote>strategies</> for this data type and this + particular roles or <quote>strategies</quote> for this data type and this index method. The operator class also specifies the support procedures to be used by the index method when the operator class is selected for an @@ -69,8 +69,8 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <para> Related operator classes can be grouped into <firstterm>operator - families</>. To add a new operator class to an existing family, - specify the <literal>FAMILY</> option in <command>CREATE OPERATOR + families</firstterm>. To add a new operator class to an existing family, + specify the <literal>FAMILY</literal> option in <command>CREATE OPERATOR CLASS</command>. Without this option, the new class is placed into a family named the same as the new class (creating that family if it doesn't already exist). @@ -96,7 +96,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </varlistentry> <varlistentry> - <term><literal>DEFAULT</></term> + <term><literal>DEFAULT</literal></term> <listitem> <para> If present, the operator class will become the default @@ -159,15 +159,15 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <term><replaceable class="parameter">op_type</replaceable></term> <listitem> <para> - In an <literal>OPERATOR</> clause, - the operand data type(s) of the operator, or <literal>NONE</> to + In an <literal>OPERATOR</literal> clause, + the operand data type(s) of the operator, or <literal>NONE</literal> to signify a left-unary or right-unary operator. The operand data types can be omitted in the normal case where they are the same as the operator class's data type. </para> <para> - In a <literal>FUNCTION</> clause, the operand data type(s) the + In a <literal>FUNCTION</literal> 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) @@ -175,7 +175,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL functions in GiST, SP-GiST, GIN and BRIN operator classes). These defaults are correct, and so <replaceable class="parameter">op_type</replaceable> need not be specified in - <literal>FUNCTION</> clauses, except for the case of a B-tree sort + <literal>FUNCTION</literal> clauses, except for the case of a B-tree sort support function that is meant to support cross-data-type comparisons. </para> </listitem> @@ -191,8 +191,8 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </para> <para> - If neither <literal>FOR SEARCH</> nor <literal>FOR ORDER BY</> is - specified, <literal>FOR SEARCH</> is the default. + If neither <literal>FOR SEARCH</literal> nor <literal>FOR ORDER BY</literal> is + specified, <literal>FOR SEARCH</literal> is the default. </para> </listitem> </varlistentry> @@ -233,11 +233,11 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL 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 and BRIN) allow it to be different. The - <literal>STORAGE</> clause must be omitted unless the index + <literal>STORAGE</literal> clause must be omitted unless the index method allows a different type to be used. - If the column <replaceable class="parameter">data_type</> is specified - as <type>anyarray</>, the <replaceable class="parameter">storage_type</> - can be declared as <type>anyelement</> to indicate that the index + If the column <replaceable class="parameter">data_type</replaceable> is specified + as <type>anyarray</type>, the <replaceable class="parameter">storage_type</replaceable> + can be declared as <type>anyelement</type> 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. </para> @@ -246,7 +246,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </variablelist> <para> - The <literal>OPERATOR</>, <literal>FUNCTION</>, and <literal>STORAGE</> + The <literal>OPERATOR</literal>, <literal>FUNCTION</literal>, and <literal>STORAGE</literal> clauses can appear in any order. </para> </refsect1> @@ -269,9 +269,9 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL </para> <para> - Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</> - clause could include a <literal>RECHECK</> option. This is no longer - supported because whether an index operator is <quote>lossy</> is now + Before <productname>PostgreSQL</productname> 8.4, the <literal>OPERATOR</literal> + clause could include a <literal>RECHECK</literal> option. This is no longer + supported because whether an index operator is <quote>lossy</quote> is now determined on-the-fly at run time. This allows efficient handling of cases where an operator might or might not be lossy. </para> @@ -282,7 +282,7 @@ CREATE OPERATOR CLASS <replaceable class="parameter">name</replaceable> [ DEFAUL <para> The following example command defines a GiST index operator class - for the data type <literal>_int4</> (array of <type>int4</type>). See the + for the data type <literal>_int4</literal> (array of <type>int4</type>). See the <xref linkend="intarray"> module for the complete example. </para> diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml index 818e3a2315a..11c38fd38be 100644 --- a/doc/src/sgml/ref/create_operator.sgml +++ b/doc/src/sgml/ref/create_operator.sgml @@ -43,7 +43,7 @@ CREATE OPERATOR <replaceable>name</replaceable> ( </para> <para> - The operator name is a sequence of up to <symbol>NAMEDATALEN</>-1 + The operator name is a sequence of up to <symbol>NAMEDATALEN</symbol>-1 (63 by default) characters from the following list: <literallayout> + - * / < > = ~ ! @ # % ^ & | ` ? @@ -72,7 +72,7 @@ CREATE OPERATOR <replaceable>name</replaceable> ( </listitem> <listitem> <para> - The use of <literal>=></> as an operator name is deprecated. It may + The use of <literal>=></literal> as an operator name is deprecated. It may be disallowed altogether in a future release. </para> </listitem> @@ -86,10 +86,10 @@ CREATE OPERATOR <replaceable>name</replaceable> ( </para> <para> - At least one of <literal>LEFTARG</> and <literal>RIGHTARG</> must be defined. For + At least one of <literal>LEFTARG</literal> and <literal>RIGHTARG</literal> must be defined. For binary operators, both must be defined. For right unary - operators, only <literal>LEFTARG</> should be defined, while for left - unary operators only <literal>RIGHTARG</> should be defined. + operators, only <literal>LEFTARG</literal> should be defined, while for left + unary operators only <literal>RIGHTARG</literal> should be defined. </para> <para> @@ -122,11 +122,11 @@ CREATE OPERATOR <replaceable>name</replaceable> ( <para> The name of the operator to be defined. See above for allowable characters. The name can be schema-qualified, for example - <literal>CREATE OPERATOR myschema.+ (...)</>. If not, then + <literal>CREATE OPERATOR myschema.+ (...)</literal>. 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 - <firstterm>overloading</>. + <firstterm>overloading</firstterm>. </para> </listitem> </varlistentry> @@ -218,7 +218,7 @@ CREATE OPERATOR <replaceable>name</replaceable> ( <para> To give a schema-qualified operator name in <replaceable class="parameter">com_op</replaceable> or the other optional - arguments, use the <literal>OPERATOR()</> syntax, for example: + arguments, use the <literal>OPERATOR()</literal> syntax, for example: <programlisting> COMMUTATOR = OPERATOR(myschema.===) , </programlisting></para> @@ -233,18 +233,18 @@ COMMUTATOR = OPERATOR(myschema.===) , <para> It is not possible to specify an operator's lexical precedence in - <command>CREATE OPERATOR</>, because the parser's precedence behavior + <command>CREATE OPERATOR</command>, because the parser's precedence behavior is hard-wired. See <xref linkend="sql-precedence"> for precedence details. </para> <para> - The obsolete options <literal>SORT1</>, <literal>SORT2</>, - <literal>LTCMP</>, and <literal>GTCMP</> were formerly used to + The obsolete options <literal>SORT1</literal>, <literal>SORT2</literal>, + <literal>LTCMP</literal>, and <literal>GTCMP</literal> 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 <literal>MERGES</> true. + for implicitly setting <literal>MERGES</literal> true. </para> <para> diff --git a/doc/src/sgml/ref/create_opfamily.sgml b/doc/src/sgml/ref/create_opfamily.sgml index c4bcf0863ef..ca5261b7a08 100644 --- a/doc/src/sgml/ref/create_opfamily.sgml +++ b/doc/src/sgml/ref/create_opfamily.sgml @@ -35,7 +35,7 @@ CREATE OPERATOR FAMILY <replaceable class="parameter">name</replaceable> USING < 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 <quote>loose</> in the operator family. + class, rather than being <quote>loose</quote> 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.) @@ -45,7 +45,7 @@ CREATE OPERATOR FAMILY <replaceable class="parameter">name</replaceable> USING < The new operator family is initially empty. It should be populated by issuing subsequent <command>CREATE OPERATOR CLASS</command> commands to add contained operator classes, and optionally - <command>ALTER OPERATOR FAMILY</command> commands to add <quote>loose</> + <command>ALTER OPERATOR FAMILY</command> commands to add <quote>loose</quote> operators and their corresponding support functions. </para> diff --git a/doc/src/sgml/ref/create_policy.sgml b/doc/src/sgml/ref/create_policy.sgml index 70df22c0593..1bcf2de4290 100644 --- a/doc/src/sgml/ref/create_policy.sgml +++ b/doc/src/sgml/ref/create_policy.sgml @@ -88,7 +88,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable <para> If row-level security is enabled for a table, but no applicable policies - exist, a <quote>default deny</> policy is assumed, so that no rows will + exist, a <quote>default deny</quote> policy is assumed, so that no rows will be visible or updatable. </para> </refsect1> @@ -188,9 +188,9 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable 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 <command>SELECT</>), and will not be - available for modification (in an <command>UPDATE</> - or <command>DELETE</>). Such rows are silently suppressed; no error + visible to the user (in a <command>SELECT</command>), and will not be + available for modification (in an <command>UPDATE</command> + or <command>DELETE</command>). Such rows are silently suppressed; no error is reported. </para> </listitem> @@ -223,7 +223,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable <variablelist> <varlistentry id="SQL-CREATEPOLICY-ALL"> - <term><literal>ALL</></term> + <term><literal>ALL</literal></term> <listitem> <para> Using <literal>ALL</literal> for a policy means that it will apply @@ -254,7 +254,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry id="SQL-CREATEPOLICY-SELECT"> - <term><literal>SELECT</></term> + <term><literal>SELECT</literal></term> <listitem> <para> Using <literal>SELECT</literal> for a policy means that it will apply @@ -274,7 +274,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry id="SQL-CREATEPOLICY-INSERT"> - <term><literal>INSERT</></term> + <term><literal>INSERT</literal></term> <listitem> <para> Using <literal>INSERT</literal> for a policy means that it will apply @@ -295,7 +295,7 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable </varlistentry> <varlistentry id="SQL-CREATEPOLICY-UPDATE"> - <term><literal>UPDATE</></term> + <term><literal>UPDATE</literal></term> <listitem> <para> Using <literal>UPDATE</literal> for a policy means that it will apply @@ -347,14 +347,14 @@ CREATE POLICY <replaceable class="parameter">name</replaceable> ON <replaceable Note, however, that unlike a standalone <literal>UPDATE</literal> command, if the existing row does not pass the <literal>USING</literal> expressions, an error will be thrown (the - <literal>UPDATE</literal> path will <emphasis>never</> be silently + <literal>UPDATE</literal> path will <emphasis>never</emphasis> be silently avoided). </para> </listitem> </varlistentry> <varlistentry id="SQL-CREATEPOLICY-DELETE"> - <term><literal>DELETE</></term> + <term><literal>DELETE</literal></term> <listitem> <para> Using <literal>DELETE</literal> for a policy means that it will apply diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml index 62a5fd432e6..b997d387e77 100644 --- a/doc/src/sgml/ref/create_publication.sgml +++ b/doc/src/sgml/ref/create_publication.sgml @@ -64,10 +64,10 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable> <listitem> <para> Specifies a list of tables to add to the publication. If - <literal>ONLY</> is specified before the table name, only - that table is added to the publication. If <literal>ONLY</> is not + <literal>ONLY</literal> is specified before the table name, only + that table is added to the publication. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are added. - Optionally, <literal>*</> can be specified after the table name to + Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> @@ -138,7 +138,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable> <para> To create a publication, the invoking user must have the - <literal>CREATE</> privilege for the current database. + <literal>CREATE</literal> privilege for the current database. (Of course, superusers bypass this check.) </para> @@ -151,12 +151,12 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable> <para> The tables added to a publication that publishes <command>UPDATE</command> and/or <command>DELETE</command> operations must have - <literal>REPLICA IDENTITY</> defined. Otherwise those operations will be + <literal>REPLICA IDENTITY</literal> defined. Otherwise those operations will be disallowed on those tables. </para> <para> - For an <command>INSERT ... ON CONFLICT</> command, the publication will + For an <command>INSERT ... ON CONFLICT</command> command, the publication will publish the operation that actually results from the command. So depending of the outcome, it may be published as either <command>INSERT</command> or <command>UPDATE</command>, or it may not be published at all. @@ -203,7 +203,7 @@ CREATE PUBLICATION insert_only FOR TABLE mydata <title>Compatibility</title> <para> - <command>CREATE PUBLICATION</command> is a <productname>PostgreSQL</> + <command>CREATE PUBLICATION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_role.sgml b/doc/src/sgml/ref/create_role.sgml index 41670c4b059..4a4061a2371 100644 --- a/doc/src/sgml/ref/create_role.sgml +++ b/doc/src/sgml/ref/create_role.sgml @@ -51,11 +51,11 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <command>CREATE ROLE</command> adds a new role to a <productname>PostgreSQL</productname> database cluster. A role is an entity that can own database objects and have database privileges; - a role can be considered a <quote>user</>, a <quote>group</>, or both + a role can be considered a <quote>user</quote>, a <quote>group</quote>, or both depending on how it is used. Refer to <xref linkend="user-manag"> and <xref linkend="client-authentication"> for information about managing - users and authentication. You must have <literal>CREATEROLE</> + users and authentication. You must have <literal>CREATEROLE</literal> privilege or be a database superuser to use this command. </para> @@ -83,7 +83,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <term><literal>NOSUPERUSER</literal></term> <listitem> <para> - These clauses determine whether the new role is a <quote>superuser</>, + These clauses determine whether the new role is a <quote>superuser</quote>, 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. @@ -94,8 +94,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </varlistentry> <varlistentry> - <term><literal>CREATEDB</></term> - <term><literal>NOCREATEDB</></term> + <term><literal>CREATEDB</literal></term> + <term><literal>NOCREATEDB</literal></term> <listitem> <para> These clauses define a role's ability to create databases. If @@ -128,13 +128,13 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <term><literal>NOINHERIT</literal></term> <listitem> <para> - These clauses determine whether a role <quote>inherits</> the + These clauses determine whether a role <quote>inherits</quote> the privileges of roles it is a member of. A role with the <literal>INHERIT</literal> attribute can automatically use whatever database privileges have been granted to all roles it is directly or indirectly a member of. Without <literal>INHERIT</literal>, membership in another role - only grants the ability to <command>SET ROLE</> to that other role; + only grants the ability to <command>SET ROLE</command> to that other role; the privileges of the other role are only available after having done so. If not specified, @@ -156,7 +156,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac privileges, but are not users in the usual sense of the word. If not specified, <literal>NOLOGIN</literal> is the default, except when - <command>CREATE ROLE</> is invoked through its alternative spelling + <command>CREATE ROLE</command> is invoked through its alternative spelling <xref linkend="sql-createuser">. </para> </listitem> @@ -172,7 +172,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac 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 <literal>REPLICATION</> attribute is a very + A role having the <literal>REPLICATION</literal> attribute is a very highly privileged role, and should only be used on roles actually used for replication. If not specified, <literal>NOREPLICATION</literal> is the default. @@ -210,7 +210,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </varlistentry> <varlistentry> - <term>[ <literal>ENCRYPTED</> ] <literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term> + <term>[ <literal>ENCRYPTED</literal> ] <literal>PASSWORD</literal> <replaceable class="parameter">password</replaceable></term> <listitem> <para> Sets the role's password. (A password is only of use for @@ -225,7 +225,7 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <note> <para> Specifying an empty string will also set the password to null, - but that was not the case before <productname>PostgreSQL</> + but that was not the case before <productname>PostgreSQL</productname> 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. @@ -235,12 +235,12 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </note> <para> The password is always stored encrypted in the system catalogs. The - <literal>ENCRYPTED</> keyword has no effect, but is accepted for + <literal>ENCRYPTED</literal> keyword has no effect, but is accepted for backwards compatibility. The method of encryption is determined by the configuration parameter <xref linkend="guc-password-encryption">. If the presented password string is already in MD5-encrypted or SCRAM-encrypted format, then it is stored as-is regardless of - <varname>password_encryption</> (since the system cannot decrypt + <varname>password_encryption</varname> (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. @@ -260,61 +260,61 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </varlistentry> <varlistentry> - <term><literal>IN ROLE</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>IN ROLE</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>IN ROLE</literal> 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 <command>GRANT</> command to do that.) + administrator; use a separate <command>GRANT</command> command to do that.) </para> </listitem> </varlistentry> <varlistentry> - <term><literal>IN GROUP</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>IN GROUP</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para><literal>IN GROUP</literal> is an obsolete spelling of - <literal>IN ROLE</>. + <literal>IN ROLE</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>ROLE</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>ROLE</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>ROLE</literal> 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 <quote>group</>.) + (This in effect makes the new role a <quote>group</quote>.) </para> </listitem> </varlistentry> <varlistentry> - <term><literal>ADMIN</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>ADMIN</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>ADMIN</literal> clause is like <literal>ROLE</literal>, but the named roles are added to the new role <literal>WITH ADMIN - OPTION</>, giving them the right to grant membership in this role + OPTION</literal>, giving them the right to grant membership in this role to others. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>USER</> <replaceable class="parameter">role_name</replaceable></term> + <term><literal>USER</literal> <replaceable class="parameter">role_name</replaceable></term> <listitem> <para> The <literal>USER</literal> clause is an obsolete spelling of - the <literal>ROLE</> clause. + the <literal>ROLE</literal> clause. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>SYSID</> <replaceable class="parameter">uid</replaceable></term> + <term><literal>SYSID</literal> <replaceable class="parameter">uid</replaceable></term> <listitem> <para> The <literal>SYSID</literal> clause is ignored, but is accepted @@ -332,8 +332,8 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac Use <xref linkend="SQL-ALTERROLE"> to change the attributes of a role, and <xref linkend="SQL-DROPROLE"> to remove a role. All the attributes - specified by <command>CREATE ROLE</> can be modified by later - <command>ALTER ROLE</> commands. + specified by <command>CREATE ROLE</command> can be modified by later + <command>ALTER ROLE</command> commands. </para> <para> @@ -344,42 +344,42 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </para> <para> - The <literal>VALID UNTIL</> clause defines an expiration time for a - password only, not for the role <foreignphrase>per se</>. In + The <literal>VALID UNTIL</literal> clause defines an expiration time for a + password only, not for the role <foreignphrase>per se</foreignphrase>. In particular, the expiration time is not enforced when logging in using a non-password-based authentication method. </para> <para> - The <literal>INHERIT</> attribute governs inheritance of grantable + The <literal>INHERIT</literal> 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 - <command>CREATE ROLE</> and <command>ALTER ROLE</>. For example, being - a member of a role with <literal>CREATEDB</> privilege does not immediately - grant the ability to create databases, even if <literal>INHERIT</> is set; + <command>CREATE ROLE</command> and <command>ALTER ROLE</command>. For example, being + a member of a role with <literal>CREATEDB</literal> privilege does not immediately + grant the ability to create databases, even if <literal>INHERIT</literal> is set; it would be necessary to become that role via <xref linkend="SQL-SET-ROLE"> before creating a database. </para> <para> - The <literal>INHERIT</> attribute is the default for reasons of backwards + The <literal>INHERIT</literal> attribute is the default for reasons of backwards compatibility: in prior releases of <productname>PostgreSQL</productname>, users always had access to all privileges of groups they were members of. - However, <literal>NOINHERIT</> provides a closer match to the semantics + However, <literal>NOINHERIT</literal> provides a closer match to the semantics specified in the SQL standard. </para> <para> - Be careful with the <literal>CREATEROLE</> privilege. There is no concept of - inheritance for the privileges of a <literal>CREATEROLE</>-role. That + Be careful with the <literal>CREATEROLE</literal> privilege. There is no concept of + inheritance for the privileges of a <literal>CREATEROLE</literal>-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 <quote>user</> has the - <literal>CREATEROLE</> privilege but not the <literal>CREATEDB</> privilege, - nonetheless it can create a new role with the <literal>CREATEDB</> - privilege. Therefore, regard roles that have the <literal>CREATEROLE</> + privileges). For example, if the role <quote>user</quote> has the + <literal>CREATEROLE</literal> privilege but not the <literal>CREATEDB</literal> privilege, + nonetheless it can create a new role with the <literal>CREATEDB</literal> + privilege. Therefore, regard roles that have the <literal>CREATEROLE</literal> privilege as almost-superuser-roles. </para> @@ -391,9 +391,9 @@ CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac </para> <para> - The <literal>CONNECTION LIMIT</> option is only enforced approximately; + The <literal>CONNECTION LIMIT</literal> option is only enforced approximately; if two new sessions start at about the same time when just one - connection <quote>slot</> remains for the role, it is possible that + connection <quote>slot</quote> remains for the role, it is possible that both will fail. Also, the limit is never enforced for superusers. </para> @@ -425,8 +425,8 @@ CREATE ROLE jonathan LOGIN; <programlisting> CREATE USER davide WITH PASSWORD 'jw8s0F4'; </programlisting> - (<command>CREATE USER</> is the same as <command>CREATE ROLE</> except - that it implies <literal>LOGIN</>.) + (<command>CREATE USER</command> is the same as <command>CREATE ROLE</command> except + that it implies <literal>LOGIN</literal>.) </para> <para> @@ -453,7 +453,7 @@ CREATE ROLE admin WITH CREATEDB CREATEROLE; The <command>CREATE ROLE</command> statement is in the SQL standard, but the standard only requires the syntax <synopsis> -CREATE ROLE <replaceable class="parameter">name</> [ WITH ADMIN <replaceable class="parameter">role_name</> ] +CREATE ROLE <replaceable class="parameter">name</replaceable> [ WITH ADMIN <replaceable class="parameter">role_name</replaceable> ] </synopsis> Multiple initial administrators, and all the other options of <command>CREATE ROLE</command>, are @@ -471,8 +471,8 @@ CREATE ROLE <replaceable class="parameter">name</> [ WITH ADMIN <replaceable cla <para> The behavior specified by the SQL standard is most closely approximated - by giving users the <literal>NOINHERIT</> attribute, while roles are - given the <literal>INHERIT</> attribute. + by giving users the <literal>NOINHERIT</literal> attribute, while roles are + given the <literal>INHERIT</literal> attribute. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_rule.sgml b/doc/src/sgml/ref/create_rule.sgml index 53fdf566214..c772c383991 100644 --- a/doc/src/sgml/ref/create_rule.sgml +++ b/doc/src/sgml/ref/create_rule.sgml @@ -76,13 +76,13 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <literal>ON DELETE</literal> rules (or any subset of those that's sufficient for your purposes) to replace update actions on the view with appropriate updates on other tables. If you want to support - <command>INSERT RETURNING</> and so on, then be sure to put a suitable - <literal>RETURNING</> clause into each of these rules. + <command>INSERT RETURNING</command> and so on, then be sure to put a suitable + <literal>RETURNING</literal> clause into each of these rules. </para> <para> There is a catch if you try to use conditional rules for complex view - updates: there <emphasis>must</> be an unconditional + updates: there <emphasis>must</emphasis> be an unconditional <literal>INSTEAD</literal> rule for each action you wish to allow on the view. If the rule is conditional, or is not <literal>INSTEAD</literal>, then the system will still reject @@ -95,7 +95,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS Then make the conditional rules non-<literal>INSTEAD</literal>; in the cases where they are applied, they add to the default <literal>INSTEAD NOTHING</literal> action. (This method does not - currently work to support <literal>RETURNING</> queries, however.) + currently work to support <literal>RETURNING</literal> queries, however.) </para> <note> @@ -108,7 +108,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS </para> <para> - Another alternative worth considering is to use <literal>INSTEAD OF</> + Another alternative worth considering is to use <literal>INSTEAD OF</literal> triggers (see <xref linkend="sql-createtrigger">) in place of rules. </para> </note> @@ -161,7 +161,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <para> Any <acronym>SQL</acronym> conditional expression (returning <type>boolean</type>). The condition expression cannot refer - to any tables except <literal>NEW</> and <literal>OLD</>, and + to any tables except <literal>NEW</literal> and <literal>OLD</literal>, and cannot contain aggregate functions. </para> </listitem> @@ -171,7 +171,7 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <term><option>INSTEAD</option></term> <listitem> <para><literal>INSTEAD</literal> indicates that the commands should be - executed <emphasis>instead of</> the original command. + executed <emphasis>instead of</emphasis> the original command. </para> </listitem> </varlistentry> @@ -227,19 +227,19 @@ CREATE [ OR REPLACE ] RULE <replaceable class="parameter">name</replaceable> AS <para> In a rule for <literal>INSERT</literal>, <literal>UPDATE</literal>, or - <literal>DELETE</literal> on a view, you can add a <literal>RETURNING</> + <literal>DELETE</literal> on a view, you can add a <literal>RETURNING</literal> clause that emits the view's columns. This clause will be used to compute - the outputs if the rule is triggered by an <command>INSERT RETURNING</>, - <command>UPDATE RETURNING</>, or <command>DELETE RETURNING</> command + the outputs if the rule is triggered by an <command>INSERT RETURNING</command>, + <command>UPDATE RETURNING</command>, or <command>DELETE RETURNING</command> command respectively. When the rule is triggered by a command without - <literal>RETURNING</>, the rule's <literal>RETURNING</> clause will be + <literal>RETURNING</literal>, the rule's <literal>RETURNING</literal> clause will be ignored. The current implementation allows only unconditional - <literal>INSTEAD</> rules to contain <literal>RETURNING</>; furthermore - there can be at most one <literal>RETURNING</> clause among all the rules + <literal>INSTEAD</literal> rules to contain <literal>RETURNING</literal>; furthermore + there can be at most one <literal>RETURNING</literal> clause among all the rules for the same event. (This ensures that there is only one candidate - <literal>RETURNING</> clause to be used to compute the results.) - <literal>RETURNING</> queries on the view will be rejected if - there is no <literal>RETURNING</> clause in any available rule. + <literal>RETURNING</literal> clause to be used to compute the results.) + <literal>RETURNING</literal> queries on the view will be rejected if + there is no <literal>RETURNING</literal> clause in any available rule. </para> <para> diff --git a/doc/src/sgml/ref/create_schema.sgml b/doc/src/sgml/ref/create_schema.sgml index ce145f96a0b..ce3530c0489 100644 --- a/doc/src/sgml/ref/create_schema.sgml +++ b/doc/src/sgml/ref/create_schema.sgml @@ -48,9 +48,9 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp 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 <quote>qualifying</> + schemas. Named objects are accessed either by <quote>qualifying</quote> their names with the schema name as a prefix, or by setting a search - path that includes the desired schema(s). A <literal>CREATE</> command + path that includes the desired schema(s). A <literal>CREATE</literal> 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 <function>current_schema</function>). @@ -60,7 +60,7 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp Optionally, <command>CREATE SCHEMA</command> 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 <literal>AUTHORIZATION</> clause is used, + schema, except that if the <literal>AUTHORIZATION</literal> clause is used, all the created objects will be owned by that user. </para> </refsect1> @@ -100,10 +100,10 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp <para> An SQL statement defining an object to be created within the schema. Currently, only <command>CREATE - TABLE</>, <command>CREATE VIEW</>, <command>CREATE - INDEX</>, <command>CREATE SEQUENCE</>, <command>CREATE - TRIGGER</> and <command>GRANT</> are accepted as clauses - within <command>CREATE SCHEMA</>. Other kinds of objects may + TABLE</command>, <command>CREATE VIEW</command>, <command>CREATE + INDEX</command>, <command>CREATE SEQUENCE</command>, <command>CREATE + TRIGGER</command> and <command>GRANT</command> are accepted as clauses + within <command>CREATE SCHEMA</command>. Other kinds of objects may be created in separate commands after the schema is created. </para> </listitem> @@ -114,7 +114,7 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp <listitem> <para> Do nothing (except issuing a notice) if a schema with the same name - already exists. <replaceable class="parameter">schema_element</> + already exists. <replaceable class="parameter">schema_element</replaceable> subcommands cannot be included when this option is used. </para> </listitem> @@ -127,7 +127,7 @@ CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_sp <para> To create a schema, the invoking user must have the - <literal>CREATE</> privilege for the current database. + <literal>CREATE</literal> privilege for the current database. (Of course, superusers bypass this check.) </para> </refsect1> @@ -143,17 +143,17 @@ CREATE SCHEMA myschema; </para> <para> - Create a schema for user <literal>joe</>; the schema will also be - named <literal>joe</>: + Create a schema for user <literal>joe</literal>; the schema will also be + named <literal>joe</literal>: <programlisting> CREATE SCHEMA AUTHORIZATION joe; </programlisting> </para> <para> - Create a schema named <literal>test</> that will be owned by user - <literal>joe</>, unless there already is a schema named <literal>test</>. - (It does not matter whether <literal>joe</> owns the pre-existing schema.) + Create a schema named <literal>test</literal> that will be owned by user + <literal>joe</literal>, unless there already is a schema named <literal>test</literal>. + (It does not matter whether <literal>joe</literal> owns the pre-existing schema.) <programlisting> CREATE SCHEMA IF NOT EXISTS test AUTHORIZATION joe; </programlisting> @@ -185,7 +185,7 @@ CREATE VIEW hollywood.winners AS <title>Compatibility</title> <para> - The SQL standard allows a <literal>DEFAULT CHARACTER SET</> clause + The SQL standard allows a <literal>DEFAULT CHARACTER SET</literal> clause in <command>CREATE SCHEMA</command>, as well as more subcommand types than are presently accepted by <productname>PostgreSQL</productname>. @@ -205,7 +205,7 @@ CREATE VIEW hollywood.winners AS all objects within it. <productname>PostgreSQL</productname> allows schemas to contain objects owned by users other than the schema owner. This can happen only if the schema owner grants the - <literal>CREATE</> privilege on their schema to someone else, or a + <literal>CREATE</literal> privilege on their schema to someone else, or a superuser chooses to create objects in it. </para> diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml index 2af8c8d23e3..9248b1d459a 100644 --- a/doc/src/sgml/ref/create_sequence.sgml +++ b/doc/src/sgml/ref/create_sequence.sgml @@ -67,10 +67,10 @@ SELECT * FROM <replaceable>name</replaceable>; </programlisting> to examine the parameters and current state of a sequence. In particular, - the <literal>last_value</> field of the sequence shows the last value + the <literal>last_value</literal> field of the sequence shows the last value allocated by any session. (Of course, this value might be obsolete by the time it's printed, if other sessions are actively doing - <function>nextval</> calls.) + <function>nextval</function> calls.) </para> </refsect1> @@ -250,14 +250,14 @@ SELECT * FROM <replaceable>name</replaceable>; </para> <para> - Sequences are based on <type>bigint</> arithmetic, so the range + Sequences are based on <type>bigint</type> arithmetic, so the range cannot exceed the range of an eight-byte integer (-9223372036854775808 to 9223372036854775807). </para> <para> - Because <function>nextval</> and <function>setval</> calls are never - rolled back, sequence objects cannot be used if <quote>gapless</> + Because <function>nextval</function> and <function>setval</function> calls are never + rolled back, sequence objects cannot be used if <quote>gapless</quote> 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 @@ -271,9 +271,9 @@ SELECT * FROM <replaceable>name</replaceable>; 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's <literal>last_value</> accordingly. + increase the sequence object's <literal>last_value</literal> accordingly. Then, the next <replaceable class="parameter">cache</replaceable>-1 - uses of <function>nextval</> within that session simply return the + uses of <function>nextval</function> 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 <quote>holes</quote> in the @@ -290,18 +290,18 @@ SELECT * FROM <replaceable>name</replaceable>; 11..20 and return <function>nextval</function>=11 before session A has generated <literal>nextval</literal>=2. Thus, with a <replaceable class="parameter">cache</replaceable> setting of one - it is safe to assume that <function>nextval</> values are generated + it is safe to assume that <function>nextval</function> values are generated sequentially; with a <replaceable class="parameter">cache</replaceable> setting greater than one you - should only assume that the <function>nextval</> values are all + should only assume that the <function>nextval</function> values are all distinct, not that they are generated purely sequentially. Also, - <literal>last_value</> will reflect the latest value reserved by + <literal>last_value</literal> will reflect the latest value reserved by any session, whether or not it has yet been returned by - <function>nextval</>. + <function>nextval</function>. </para> <para> - Another consideration is that a <function>setval</> executed on + Another consideration is that a <function>setval</function> executed on such a sequence will not be noticed by other sessions until they have used up any preallocated values they have cached. </para> @@ -365,14 +365,14 @@ END; <itemizedlist> <listitem> <para> - Obtaining the next value is done using the <function>nextval()</> + Obtaining the next value is done using the <function>nextval()</function> function instead of the standard's <command>NEXT VALUE FOR</command> expression. </para> </listitem> <listitem> <para> - The <literal>OWNED BY</> clause is a <productname>PostgreSQL</> + The <literal>OWNED BY</literal> clause is a <productname>PostgreSQL</productname> extension. </para> </listitem> diff --git a/doc/src/sgml/ref/create_server.sgml b/doc/src/sgml/ref/create_server.sgml index 47b8a6291bb..e14ce43bf9e 100644 --- a/doc/src/sgml/ref/create_server.sgml +++ b/doc/src/sgml/ref/create_server.sgml @@ -47,7 +47,7 @@ CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replac </para> <para> - Creating a server requires <literal>USAGE</> privilege on the + Creating a server requires <literal>USAGE</literal> privilege on the foreign-data wrapper being used. </para> </refsect1> @@ -57,7 +57,7 @@ CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replac <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a server with the same name already exists. @@ -135,8 +135,8 @@ CREATE SERVER [IF NOT EXISTS] <replaceable class="parameter">server_name</replac <title>Examples</title> <para> - Create a server <literal>myserver</> that uses the - foreign-data wrapper <literal>postgres_fdw</>: + Create a server <literal>myserver</literal> that uses the + foreign-data wrapper <literal>postgres_fdw</literal>: <programlisting> CREATE SERVER myserver FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host 'foo', dbname 'foodb', port '5432'); </programlisting> diff --git a/doc/src/sgml/ref/create_statistics.sgml b/doc/src/sgml/ref/create_statistics.sgml index 0d68ca06b72..066af8a4b4d 100644 --- a/doc/src/sgml/ref/create_statistics.sgml +++ b/doc/src/sgml/ref/create_statistics.sgml @@ -41,7 +41,7 @@ CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="parameter">statistics_na <para> If a schema name is given (for example, <literal>CREATE STATISTICS - myschema.mystat ...</>) then the statistics object is created in the + myschema.mystat ...</literal>) 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. @@ -54,7 +54,7 @@ CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="parameter">statistics_na <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a statistics object with the same name already @@ -129,7 +129,7 @@ CREATE STATISTICS [ IF NOT EXISTS ] <replaceable class="parameter">statistics_na <title>Examples</title> <para> - Create table <structname>t1</> with two functionally dependent columns, i.e. + Create table <structname>t1</structname> 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: @@ -157,10 +157,10 @@ EXPLAIN ANALYZE SELECT * FROM t1 WHERE (a = 1) AND (b = 0); </programlisting> Without functional-dependency statistics, the planner would assume - that the two <literal>WHERE</> conditions are independent, and would + that the two <literal>WHERE</literal> 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 <literal>WHERE</> + With such statistics, the planner recognizes that the <literal>WHERE</literal> conditions are redundant and does not underestimate the rowcount. </para> diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml index bae9f839bd2..cd51b7fcac5 100644 --- a/doc/src/sgml/ref/create_subscription.sgml +++ b/doc/src/sgml/ref/create_subscription.sgml @@ -201,7 +201,7 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl to <literal>false</literal>, the tables are not subscribed, and so after you enable the subscription nothing will be replicated. It is required to run - <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</> in order + <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> in order for tables to be subscribed. </para> </listitem> @@ -272,7 +272,7 @@ CREATE SUBSCRIPTION mysub <title>Compatibility</title> <para> - <command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</> + <command>CREATE SUBSCRIPTION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml index d15795857b1..2db2e9fc444 100644 --- a/doc/src/sgml/ref/create_table.sgml +++ b/doc/src/sgml/ref/create_table.sgml @@ -113,7 +113,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> If a schema name is given (for example, <literal>CREATE TABLE - myschema.mytable ...</>) then the table is created in the specified + myschema.mytable ...</literal>) 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 @@ -158,7 +158,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <variablelist> <varlistentry id="SQL-CREATETABLE-TEMPORARY"> - <term><literal>TEMPORARY</> or <literal>TEMP</></term> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> <listitem> <para> If specified, the table is created as a temporary table. @@ -177,13 +177,13 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace 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 - <command>ANALYZE</> on the temporary table after it is populated. + <command>ANALYZE</command> on the temporary table after it is populated. </para> <para> Optionally, <literal>GLOBAL</literal> or <literal>LOCAL</literal> - can be written before <literal>TEMPORARY</> or <literal>TEMP</>. - This presently makes no difference in <productname>PostgreSQL</> + can be written before <literal>TEMPORARY</literal> or <literal>TEMP</literal>. + This presently makes no difference in <productname>PostgreSQL</productname> and is deprecated; see <xref linkend="sql-createtable-compatibility" endterm="sql-createtable-compatibility-title">. @@ -192,7 +192,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry id="SQL-CREATETABLE-UNLOGGED"> - <term><literal>UNLOGGED</></term> + <term><literal>UNLOGGED</literal></term> <listitem> <para> If specified, the table is created as an unlogged table. Data written @@ -208,7 +208,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a relation with the same name already exists. @@ -263,14 +263,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace The <replaceable class="parameter">partition_bound_spec</replaceable> 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 <literal>IN</> is used for list partitioning, - while the form with <literal>FROM</> and <literal>TO</> is used for + parent. The form with <literal>IN</literal> is used for list partitioning, + while the form with <literal>FROM</literal> and <literal>TO</literal> is used for range partitioning. </para> <para> Each of the values specified in - the <replaceable class="parameter">partition_bound_spec</> is + the <replaceable class="parameter">partition_bound_spec</replaceable> is a literal, <literal>NULL</literal>, <literal>MINVALUE</literal>, or <literal>MAXVALUE</literal>. Each literal value must be either a numeric constant that is coercible to the corresponding partition key @@ -294,52 +294,52 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace partition, whereas those in the <literal>TO</literal> list are not. Note that this statement must be understood according to the rules of row-wise comparison (<xref linkend="row-wise-comparison">). - For example, given <literal>PARTITION BY RANGE (x,y)</>, a partition + For example, given <literal>PARTITION BY RANGE (x,y)</literal>, a partition bound <literal>FROM (1, 2) TO (3, 4)</literal> - allows <literal>x=1</> with any <literal>y>=2</>, - <literal>x=2</> with any non-null <literal>y</>, - and <literal>x=3</> with any <literal>y<4</>. + allows <literal>x=1</literal> with any <literal>y>=2</literal>, + <literal>x=2</literal> with any non-null <literal>y</literal>, + and <literal>x=3</literal> with any <literal>y<4</literal>. </para> <para> - The special values <literal>MINVALUE</> and <literal>MAXVALUE</> + The special values <literal>MINVALUE</literal> and <literal>MAXVALUE</literal> may be used when creating a range partition to indicate that there is no lower or upper bound on the column's value. For example, a - partition defined using <literal>FROM (MINVALUE) TO (10)</> allows + partition defined using <literal>FROM (MINVALUE) TO (10)</literal> allows any values less than 10, and a partition defined using - <literal>FROM (10) TO (MAXVALUE)</> allows any values greater than + <literal>FROM (10) TO (MAXVALUE)</literal> allows any values greater than or equal to 10. </para> <para> When creating a range partition involving more than one column, it - can also make sense to use <literal>MAXVALUE</> as part of the lower - bound, and <literal>MINVALUE</> as part of the upper bound. For + can also make sense to use <literal>MAXVALUE</literal> as part of the lower + bound, and <literal>MINVALUE</literal> as part of the upper bound. For example, a partition defined using - <literal>FROM (0, MAXVALUE) TO (10, MAXVALUE)</> allows any rows + <literal>FROM (0, MAXVALUE) TO (10, MAXVALUE)</literal> 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 - <literal>FROM ('a', MINVALUE) TO ('b', MINVALUE)</> allows any rows + <literal>FROM ('a', MINVALUE) TO ('b', MINVALUE)</literal> allows any rows where the first partition key column starts with "a". </para> <para> - Note that if <literal>MINVALUE</> or <literal>MAXVALUE</> is used for + Note that if <literal>MINVALUE</literal> or <literal>MAXVALUE</literal> is used for one column of a partitioning bound, the same value must be used for all - subsequent columns. For example, <literal>(10, MINVALUE, 0)</> is not - a valid bound; you should write <literal>(10, MINVALUE, MINVALUE)</>. + subsequent columns. For example, <literal>(10, MINVALUE, 0)</literal> is not + a valid bound; you should write <literal>(10, MINVALUE, MINVALUE)</literal>. </para> <para> - Also note that some element types, such as <literal>timestamp</>, + Also note that some element types, such as <literal>timestamp</literal>, have a notion of "infinity", which is just another value that can - be stored. This is different from <literal>MINVALUE</> and - <literal>MAXVALUE</>, which are not real values that can be stored, + be stored. This is different from <literal>MINVALUE</literal> and + <literal>MAXVALUE</literal>, which are not real values that can be stored, but rather they are ways of saying that the value is unbounded. - <literal>MAXVALUE</> can be thought of as being greater than any - other value, including "infinity" and <literal>MINVALUE</> as being + <literal>MAXVALUE</literal> can be thought of as being greater than any + other value, including "infinity" and <literal>MINVALUE</literal> as being less than any other value, including "minus infinity". Thus the range - <literal>FROM ('infinity') TO (MAXVALUE)</> is not an empty range; it + <literal>FROM ('infinity') TO (MAXVALUE)</literal> is not an empty range; it allows precisely one value to be stored — "infinity". </para> @@ -370,9 +370,9 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace column will be inherited by all partitions just like any other column. Modifications to the column names or types of a partitioned table, or the addition or removal of an OID column, will automatically propagate - to all partitions. <literal>CHECK</> constraints will be inherited + to all partitions. <literal>CHECK</literal> constraints will be inherited automatically by every partition, but an individual partition may specify - additional <literal>CHECK</> constraints; additional constraints with + additional <literal>CHECK</literal> 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. @@ -421,7 +421,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>COLLATE <replaceable>collation</replaceable></literal></term> <listitem> <para> - The <literal>COLLATE</> clause assigns a collation to + The <literal>COLLATE</literal> clause assigns a collation to the column (which must be of a collatable data type). If not specified, the column data type's default collation is used. </para> @@ -432,13 +432,13 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>INHERITS ( <replaceable>parent_table</replaceable> [, ... ] )</literal></term> <listitem> <para> - The optional <literal>INHERITS</> clause specifies a list of + The optional <literal>INHERITS</literal> clause specifies a list of tables from which the new table automatically inherits all columns. Parent tables can be plain tables or foreign tables. </para> <para> - Use of <literal>INHERITS</> creates a persistent relationship + Use of <literal>INHERITS</literal> 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 @@ -462,19 +462,19 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> - <literal>CHECK</> constraints are merged in essentially the same way as + <literal>CHECK</literal> constraints are merged in essentially the same way as columns: if multiple parent tables and/or the new table definition - contain identically-named <literal>CHECK</> constraints, these + contain identically-named <literal>CHECK</literal> 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 <literal>NO INHERIT</> in a - parent will not be considered. Notice that an unnamed <literal>CHECK</> + be merged into one copy. A constraint marked <literal>NO INHERIT</literal> in a + parent will not be considered. Notice that an unnamed <literal>CHECK</literal> constraint in the new table will never be merged, since a unique name will always be chosen for it. </para> <para> - Column <literal>STORAGE</> settings are also copied from parent tables. + Column <literal>STORAGE</literal> settings are also copied from parent tables. </para> <para> @@ -504,7 +504,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> A partitioned table is divided into sub-tables (called partitions), - which are created using separate <literal>CREATE TABLE</> commands. + which are created using separate <literal>CREATE TABLE</literal> 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 @@ -542,7 +542,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace default behavior is to exclude default expressions, resulting in the copied columns in the new table having null defaults. Note that copying defaults that call database-modification functions, - such as <function>nextval</>, may create a functional linkage between + such as <function>nextval</function>, may create a functional linkage between the original and new tables. </para> <para> @@ -559,8 +559,8 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace constraints. </para> <para> - Indexes, <literal>PRIMARY KEY</>, <literal>UNIQUE</>, - and <literal>EXCLUDE</> constraints on the original table will be + Indexes, <literal>PRIMARY KEY</literal>, <literal>UNIQUE</literal>, + and <literal>EXCLUDE</literal> constraints on the original table will be created on the new table only if <literal>INCLUDING INDEXES</literal> is specified. Names for the new indexes and constraints are chosen according to the default rules, regardless of how the originals @@ -568,11 +568,11 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace the new indexes.) </para> <para> - <literal>STORAGE</> settings for the copied column definitions will be + <literal>STORAGE</literal> settings for the copied column definitions will be copied only if <literal>INCLUDING STORAGE</literal> is specified. The - default behavior is to exclude <literal>STORAGE</> settings, resulting + default behavior is to exclude <literal>STORAGE</literal> settings, resulting in the copied columns in the new table having type-specific default - settings. For more on <literal>STORAGE</> settings, see + settings. For more on <literal>STORAGE</literal> settings, see <xref linkend="storage-toast">. </para> <para> @@ -587,7 +587,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> Note that unlike <literal>INHERITS</literal>, columns and - constraints copied by <literal>LIKE</> are not merged with similarly + constraints copied by <literal>LIKE</literal> are not merged with similarly named columns and constraints. If the same name is specified explicitly or in another <literal>LIKE</literal> clause, an error is signaled. @@ -607,7 +607,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> 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 <literal>col must be positive</> can be used + so constraint names like <literal>col must be positive</literal> 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. @@ -616,7 +616,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>NOT NULL</></term> + <term><literal>NOT NULL</literal></term> <listitem> <para> The column is not allowed to contain null values. @@ -625,7 +625,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>NULL</></term> + <term><literal>NULL</literal></term> <listitem> <para> The column is allowed to contain null values. This is the default. @@ -643,7 +643,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>CHECK ( <replaceable class="parameter">expression</replaceable> ) [ NO INHERIT ] </literal></term> <listitem> <para> - The <literal>CHECK</> clause specifies an expression producing a + The <literal>CHECK</literal> 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 @@ -662,15 +662,15 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> - A constraint marked with <literal>NO INHERIT</> will not propagate to + A constraint marked with <literal>NO INHERIT</literal> will not propagate to child tables. </para> <para> When a table has multiple <literal>CHECK</literal> constraints, they will be tested for each row in alphabetical order by name, - after checking <literal>NOT NULL</> constraints. - (<productname>PostgreSQL</> versions before 9.5 did not honor any + after checking <literal>NOT NULL</literal> constraints. + (<productname>PostgreSQL</productname> versions before 9.5 did not honor any particular firing order for <literal>CHECK</literal> constraints.) </para> </listitem> @@ -681,7 +681,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <replaceable>default_expr</replaceable></literal></term> <listitem> <para> - The <literal>DEFAULT</> clause assigns a default data value for + The <literal>DEFAULT</literal> 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 @@ -729,8 +729,8 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>UNIQUE</> (column constraint)</term> - <term><literal>UNIQUE ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</> (table constraint)</term> + <term><literal>UNIQUE</literal> (column constraint)</term> + <term><literal>UNIQUE ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</literal> (table constraint)</term> <listitem> <para> @@ -756,11 +756,11 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>PRIMARY KEY</> (column constraint)</term> - <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</> (table constraint)</term> + <term><literal>PRIMARY KEY</literal> (column constraint)</term> + <term><literal>PRIMARY KEY ( <replaceable class="parameter">column_name</replaceable> [, ... ] )</literal> (table constraint)</term> <listitem> <para> - The <literal>PRIMARY KEY</> constraint specifies that a column or + The <literal>PRIMARY KEY</literal> 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. @@ -775,7 +775,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> <literal>PRIMARY KEY</literal> enforces the same data constraints as - a combination of <literal>UNIQUE</> and <literal>NOT NULL</>, but + a combination of <literal>UNIQUE</literal> and <literal>NOT NULL</literal>, but 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. @@ -787,19 +787,19 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <term><literal>EXCLUDE [ USING <replaceable class="parameter">index_method</replaceable> ] ( <replaceable class="parameter">exclude_element</replaceable> WITH <replaceable class="parameter">operator</replaceable> [, ... ] ) <replaceable class="parameter">index_parameters</replaceable> [ WHERE ( <replaceable class="parameter">predicate</replaceable> ) ]</literal></term> <listitem> <para> - The <literal>EXCLUDE</> clause defines an exclusion + The <literal>EXCLUDE</literal> 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 <literal>TRUE</>. If all of the + comparisons will return <literal>TRUE</literal>. If all of the specified operators test for equality, this is equivalent to a - <literal>UNIQUE</> constraint, although an ordinary unique constraint + <literal>UNIQUE</literal> 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 <xref linkend="datatype-geometric">) by using the - <literal>&&</> operator. + <literal>&&</literal> operator. </para> <para> @@ -807,7 +807,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace an index, so each specified operator must be associated with an appropriate operator class (see <xref linkend="indexes-opclass">) for the index access - method <replaceable>index_method</>. + method <replaceable>index_method</replaceable>. The operators are required to be commutative. Each <replaceable class="parameter">exclude_element</replaceable> can optionally specify an operator class and/or ordering options; @@ -816,17 +816,17 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </para> <para> - The access method must support <literal>amgettuple</> (see <xref - linkend="indexam">); at present this means <acronym>GIN</> + The access method must support <literal>amgettuple</literal> (see <xref + linkend="indexam">); at present this means <acronym>GIN</acronym> cannot be used. Although it's 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't do better. - So in practice the access method will always be <acronym>GiST</> or - <acronym>SP-GiST</>. + So in practice the access method will always be <acronym>GiST</acronym> or + <acronym>SP-GiST</acronym>. </para> <para> - The <replaceable class="parameter">predicate</> allows you to specify an + The <replaceable class="parameter">predicate</replaceable> 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. </para> @@ -853,7 +853,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace primary key of the <replaceable class="parameter">reftable</replaceable> 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 <literal>REFERENCES</> permission on the referenced table + must have <literal>REFERENCES</literal> permission on the referenced table (either the whole table, or the specific referenced columns). Note that foreign key constraints cannot be defined between temporary tables and permanent tables. @@ -863,16 +863,16 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace 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: <literal>MATCH - FULL</>, <literal>MATCH PARTIAL</>, and <literal>MATCH + FULL</literal>, <literal>MATCH PARTIAL</literal>, and <literal>MATCH SIMPLE</literal> (which is the default). <literal>MATCH - FULL</> will not allow one column of a multicolumn foreign key + FULL</literal> 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. <literal>MATCH SIMPLE</literal> 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. - <literal>MATCH PARTIAL</> is not yet implemented. - (Of course, <literal>NOT NULL</> constraints can be applied to the + <literal>MATCH PARTIAL</literal> is not yet implemented. + (Of course, <literal>NOT NULL</literal> constraints can be applied to the referencing column(s) to prevent these cases from arising.) </para> @@ -969,13 +969,13 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace deferrable can be postponed until the end of the transaction (using the <xref linkend="sql-set-constraints"> command). <literal>NOT DEFERRABLE</literal> is the default. - Currently, only <literal>UNIQUE</>, <literal>PRIMARY KEY</>, - <literal>EXCLUDE</>, and - <literal>REFERENCES</> (foreign key) constraints accept this - clause. <literal>NOT NULL</> and <literal>CHECK</> constraints are not + Currently, only <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, + <literal>EXCLUDE</literal>, and + <literal>REFERENCES</literal> (foreign key) constraints accept this + clause. <literal>NOT NULL</literal> and <literal>CHECK</literal> constraints are not deferrable. Note that deferrable constraints cannot be used as conflict arbitrators in an <command>INSERT</command> statement that - includes an <literal>ON CONFLICT DO UPDATE</> clause. + includes an <literal>ON CONFLICT DO UPDATE</literal> clause. </para> </listitem> </varlistentry> @@ -1003,16 +1003,16 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace This clause specifies optional storage parameters for a table or index; see <xref linkend="sql-createtable-storage-parameters" endterm="sql-createtable-storage-parameters-title"> for more - information. The <literal>WITH</> clause for a - table can also include <literal>OIDS=TRUE</> (or just <literal>OIDS</>) + information. The <literal>WITH</literal> clause for a + table can also include <literal>OIDS=TRUE</literal> (or just <literal>OIDS</literal>) to specify that rows of the new table should have OIDs (object identifiers) assigned to them, or - <literal>OIDS=FALSE</> to specify that the rows should not have OIDs. - If <literal>OIDS</> is not specified, the default setting depends upon + <literal>OIDS=FALSE</literal> to specify that the rows should not have OIDs. + If <literal>OIDS</literal> is not specified, the default setting depends upon the <xref linkend="guc-default-with-oids"> configuration parameter. (If the new table inherits from any tables that have OIDs, then - <literal>OIDS=TRUE</> is forced even if the command says - <literal>OIDS=FALSE</>.) + <literal>OIDS=TRUE</literal> is forced even if the command says + <literal>OIDS=FALSE</literal>.) </para> <para> @@ -1035,14 +1035,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>WITH OIDS</></term> - <term><literal>WITHOUT OIDS</></term> + <term><literal>WITH OIDS</literal></term> + <term><literal>WITHOUT OIDS</literal></term> <listitem> <para> - These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</> - and <literal>WITH (OIDS=FALSE)</>, respectively. If you wish to give - both an <literal>OIDS</> setting and storage parameters, you must use - the <literal>WITH ( ... )</> syntax; see above. + These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</literal> + and <literal>WITH (OIDS=FALSE)</literal>, respectively. If you wish to give + both an <literal>OIDS</literal> setting and storage parameters, you must use + the <literal>WITH ( ... )</literal> syntax; see above. </para> </listitem> </varlistentry> @@ -1110,7 +1110,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> This clause allows selection of the tablespace in which the index associated with a <literal>UNIQUE</literal>, <literal>PRIMARY - KEY</literal>, or <literal>EXCLUDE</> constraint will be created. + KEY</literal>, or <literal>EXCLUDE</literal> constraint will be created. If not specified, <xref linkend="guc-default-tablespace"> is consulted, or <xref linkend="guc-temp-tablespaces"> if the table is temporary. @@ -1128,16 +1128,16 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </indexterm> <para> - The <literal>WITH</> clause can specify <firstterm>storage parameters</> + The <literal>WITH</literal> clause can specify <firstterm>storage parameters</firstterm> for tables, and for indexes associated with a <literal>UNIQUE</literal>, - <literal>PRIMARY KEY</literal>, or <literal>EXCLUDE</> constraint. + <literal>PRIMARY KEY</literal>, or <literal>EXCLUDE</literal> constraint. Storage parameters for indexes are documented in <xref linkend="SQL-CREATEINDEX">. 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 <literal>toast.</literal>, which controls the behavior of the - table's secondary <acronym>TOAST</> table, if any + table's secondary <acronym>TOAST</acronym> table, if any (see <xref linkend="storage-toast"> for more information about TOAST). If a table parameter value is set and the equivalent <literal>toast.</literal> parameter is not, the TOAST table @@ -1149,14 +1149,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <variablelist> <varlistentry> - <term><literal>fillfactor</> (<type>integer</>)</term> + <term><literal>fillfactor</literal> (<type>integer</type>)</term> <listitem> <para> The fillfactor for a table is a percentage between 10 and 100. 100 (complete packing) is the default. When a smaller fillfactor - is specified, <command>INSERT</> operations pack table pages only + is specified, <command>INSERT</command> 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 <command>UPDATE</> + reserved for updating rows on that page. This gives <command>UPDATE</command> 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. For a table whose entries are never updated, complete packing is the @@ -1167,7 +1167,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>parallel_workers</> (<type>integer</>)</term> + <term><literal>parallel_workers</literal> (<type>integer</type>)</term> <listitem> <para> This sets the number of workers that should be used to assist a parallel @@ -1180,12 +1180,12 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_enabled</>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</>)</term> + <term><literal>autovacuum_enabled</literal>, <literal>toast.autovacuum_enabled</literal> (<type>boolean</type>)</term> <listitem> <para> Enables or disables the autovacuum daemon for a particular table. - If true, the autovacuum daemon will perform automatic <command>VACUUM</> - and/or <command>ANALYZE</> operations on this table following the rules + If true, the autovacuum daemon will perform automatic <command>VACUUM</command> + and/or <command>ANALYZE</command> operations on this table following the rules discussed in <xref linkend="autovacuum">. If false, this table will not be autovacuumed, except to prevent transaction ID wraparound. See <xref linkend="vacuum-for-wraparound"> for @@ -1194,14 +1194,14 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace transaction ID wraparound) if the <xref linkend="guc-autovacuum"> parameter is false; setting individual tables' storage parameters does not override that. Therefore there is seldom much point in explicitly - setting this storage parameter to <literal>true</>, only - to <literal>false</>. + setting this storage parameter to <literal>true</literal>, only + to <literal>false</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_threshold</>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</>)</term> + <term><literal>autovacuum_vacuum_threshold</literal>, <literal>toast.autovacuum_vacuum_threshold</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-threshold"> @@ -1211,7 +1211,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_scale_factor</>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>float4</>)</term> + <term><literal>autovacuum_vacuum_scale_factor</literal>, <literal>toast.autovacuum_vacuum_scale_factor</literal> (<type>float4</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-scale-factor"> @@ -1221,7 +1221,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_analyze_threshold</> (<type>integer</>)</term> + <term><literal>autovacuum_analyze_threshold</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-analyze-threshold"> @@ -1231,7 +1231,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_analyze_scale_factor</> (<type>float4</>)</term> + <term><literal>autovacuum_analyze_scale_factor</literal> (<type>float4</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-analyze-scale-factor"> @@ -1241,7 +1241,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_cost_delay</>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>integer</>)</term> + <term><literal>autovacuum_vacuum_cost_delay</literal>, <literal>toast.autovacuum_vacuum_cost_delay</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-delay"> @@ -1251,7 +1251,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_vacuum_cost_limit</>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</>)</term> + <term><literal>autovacuum_vacuum_cost_limit</literal>, <literal>toast.autovacuum_vacuum_cost_limit</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-vacuum-cost-limit"> @@ -1261,12 +1261,12 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_freeze_min_age</>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</>)</term> + <term><literal>autovacuum_freeze_min_age</literal>, <literal>toast.autovacuum_freeze_min_age</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-vacuum-freeze-min-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_freeze_min_age</> parameters that are + per-table <literal>autovacuum_freeze_min_age</literal> parameters that are larger than half the system-wide <xref linkend="guc-autovacuum-freeze-max-age"> setting. </para> @@ -1274,12 +1274,12 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace </varlistentry> <varlistentry> - <term><literal>autovacuum_freeze_max_age</>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</>)</term> + <term><literal>autovacuum_freeze_max_age</literal>, <literal>toast.autovacuum_freeze_max_age</literal> (<type>integer</type>)</term> <listitem> <para> Per-table value for <xref linkend="guc-autovacuum-freeze-max-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_freeze_max_age</> parameters that are + per-table <literal>autovacuum_freeze_max_age</literal> parameters that are larger than the system-wide setting (it can only be set smaller). </para> </listitem> @@ -1301,7 +1301,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <para> Per-table value for <xref linkend="guc-vacuum-multixact-freeze-min-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_multixact_freeze_min_age</> parameters + per-table <literal>autovacuum_multixact_freeze_min_age</literal> parameters that are larger than half the system-wide <xref linkend="guc-autovacuum-multixact-freeze-max-age"> setting. @@ -1316,7 +1316,7 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace Per-table value for <xref linkend="guc-autovacuum-multixact-freeze-max-age"> parameter. Note that autovacuum will ignore - per-table <literal>autovacuum_multixact_freeze_max_age</> parameters + per-table <literal>autovacuum_multixact_freeze_max_age</literal> parameters that are larger than the system-wide setting (it can only be set smaller). </para> @@ -1369,11 +1369,11 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace generator as the table's primary key is preferred. However, if your application does make use of OIDs to identify specific rows of a table, it is recommended to create a unique constraint - on the <structfield>oid</> column of that table, to ensure that + on the <structfield>oid</structfield> column of that table, to ensure that OIDs in the table will indeed uniquely identify rows even after counter wraparound. Avoid assuming that OIDs are unique across tables; if you need a database-wide unique identifier, use the - combination of <structfield>tableoid</> and row OID for the + combination of <structfield>tableoid</structfield> and row OID for the purpose. </para> @@ -1411,8 +1411,8 @@ FROM ( { <replaceable class="parameter">numeric_literal</replaceable> | <replace <title>Examples</title> <para> - Create table <structname>films</> and table - <structname>distributors</>: + Create table <structname>films</structname> and table + <structname>distributors</structname>: <programlisting> CREATE TABLE films ( @@ -1484,7 +1484,7 @@ CREATE TABLE distributors ( <para> Define a primary key table constraint for the table - <structname>films</>: + <structname>films</structname>: <programlisting> CREATE TABLE films ( @@ -1501,7 +1501,7 @@ CREATE TABLE films ( <para> Define a primary key constraint for table - <structname>distributors</>. The following two examples are + <structname>distributors</structname>. The following two examples are equivalent, the first using the table constraint syntax, the second the column constraint syntax: @@ -1537,7 +1537,7 @@ CREATE TABLE distributors ( </para> <para> - Define two <literal>NOT NULL</> column constraints on the table + Define two <literal>NOT NULL</literal> column constraints on the table <classname>distributors</classname>, one of which is explicitly given a name: @@ -1585,7 +1585,7 @@ WITH (fillfactor=70); </para> <para> - Create table <structname>circles</> with an exclusion + Create table <structname>circles</structname> with an exclusion constraint that prevents any two circles from overlapping: <programlisting> @@ -1597,7 +1597,7 @@ CREATE TABLE circles ( </para> <para> - Create table <structname>cinemas</> in tablespace <structname>diskvol1</>: + Create table <structname>cinemas</structname> in tablespace <structname>diskvol1</structname>: <programlisting> CREATE TABLE cinemas ( @@ -1761,8 +1761,8 @@ CREATE TABLE cities_partdef <para> The <literal>ON COMMIT</literal> clause for temporary tables also resembles the SQL standard, but has some differences. - If the <literal>ON COMMIT</> clause is omitted, SQL specifies that the - default behavior is <literal>ON COMMIT DELETE ROWS</>. However, the + If the <literal>ON COMMIT</literal> clause is omitted, SQL specifies that the + default behavior is <literal>ON COMMIT DELETE ROWS</literal>. However, the default behavior in <productname>PostgreSQL</productname> is <literal>ON COMMIT PRESERVE ROWS</literal>. The <literal>ON COMMIT DROP</literal> option does not exist in SQL. @@ -1773,15 +1773,15 @@ CREATE TABLE cities_partdef <title>Non-deferred Uniqueness Constraints</title> <para> - When a <literal>UNIQUE</> or <literal>PRIMARY KEY</> constraint is + When a <literal>UNIQUE</literal> or <literal>PRIMARY KEY</literal> constraint is not deferrable, <productname>PostgreSQL</productname> 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 - <literal>DEFERRABLE</> but not deferred (i.e., <literal>INITIALLY - IMMEDIATE</>). Be aware that this can be significantly slower than + <literal>DEFERRABLE</literal> but not deferred (i.e., <literal>INITIALLY + IMMEDIATE</literal>). Be aware that this can be significantly slower than immediate uniqueness checking. </para> </refsect2> @@ -1790,8 +1790,8 @@ CREATE TABLE cities_partdef <title>Column Check Constraints</title> <para> - The SQL standard says that <literal>CHECK</> column constraints - can only refer to the column they apply to; only <literal>CHECK</> + The SQL standard says that <literal>CHECK</literal> column constraints + can only refer to the column they apply to; only <literal>CHECK</literal> table constraints can refer to multiple columns. <productname>PostgreSQL</productname> does not enforce this restriction; it treats column and table check constraints alike. @@ -1802,7 +1802,7 @@ CREATE TABLE cities_partdef <title><literal>EXCLUDE</literal> Constraint</title> <para> - The <literal>EXCLUDE</> constraint type is a + The <literal>EXCLUDE</literal> constraint type is a <productname>PostgreSQL</productname> extension. </para> </refsect2> @@ -1811,7 +1811,7 @@ CREATE TABLE cities_partdef <title><literal>NULL</literal> <quote>Constraint</quote></title> <para> - The <literal>NULL</> <quote>constraint</quote> (actually a + The <literal>NULL</literal> <quote>constraint</quote> (actually a non-constraint) is a <productname>PostgreSQL</productname> extension to the SQL standard that is included for compatibility with some other database systems (and for symmetry with the <literal>NOT @@ -1838,11 +1838,11 @@ CREATE TABLE cities_partdef <para> <productname>PostgreSQL</productname> allows a table of no columns - to be created (for example, <literal>CREATE TABLE foo();</>). This + to be created (for example, <literal>CREATE TABLE foo();</literal>). 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 <command>ALTER TABLE - DROP COLUMN</>, so it seems cleaner to ignore this spec restriction. + DROP COLUMN</command>, so it seems cleaner to ignore this spec restriction. </para> </refsect2> @@ -1861,10 +1861,10 @@ CREATE TABLE cities_partdef </refsect2> <refsect2> - <title><literal>LIKE</> Clause</title> + <title><literal>LIKE</literal> Clause</title> <para> - While a <literal>LIKE</> clause exists in the SQL standard, many of the + While a <literal>LIKE</literal> clause exists in the SQL standard, many of the options that <productname>PostgreSQL</productname> accepts for it are not in the standard, and some of the standard's options are not implemented by <productname>PostgreSQL</productname>. @@ -1872,10 +1872,10 @@ CREATE TABLE cities_partdef </refsect2> <refsect2> - <title><literal>WITH</> Clause</title> + <title><literal>WITH</literal> Clause</title> <para> - The <literal>WITH</> clause is a <productname>PostgreSQL</productname> + The <literal>WITH</literal> clause is a <productname>PostgreSQL</productname> extension; neither storage parameters nor OIDs are in the standard. </para> </refsect2> @@ -1904,19 +1904,19 @@ CREATE TABLE cities_partdef </refsect2> <refsect2> - <title><literal>PARTITION BY</> Clause</title> + <title><literal>PARTITION BY</literal> Clause</title> <para> - The <literal>PARTITION BY</> clause is a + The <literal>PARTITION BY</literal> clause is a <productname>PostgreSQL</productname> extension. </para> </refsect2> <refsect2> - <title><literal>PARTITION OF</> Clause</title> + <title><literal>PARTITION OF</literal> Clause</title> <para> - The <literal>PARTITION OF</> clause is a + The <literal>PARTITION OF</literal> clause is a <productname>PostgreSQL</productname> extension. </para> </refsect2> diff --git a/doc/src/sgml/ref/create_table_as.sgml b/doc/src/sgml/ref/create_table_as.sgml index 0fa28a11fa7..8198442a974 100644 --- a/doc/src/sgml/ref/create_table_as.sgml +++ b/doc/src/sgml/ref/create_table_as.sgml @@ -71,7 +71,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI <variablelist> <varlistentry> - <term><literal>TEMPORARY</> or <literal>TEMP</></term> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> <listitem> <para> If specified, the table is created as a temporary table. @@ -81,7 +81,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </varlistentry> <varlistentry> - <term><literal>UNLOGGED</></term> + <term><literal>UNLOGGED</literal></term> <listitem> <para> If specified, the table is created as an unlogged table. @@ -91,7 +91,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI </varlistentry> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a relation with the same name already exists. @@ -127,25 +127,25 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI This clause specifies optional storage parameters for the new table; see <xref linkend="sql-createtable-storage-parameters" endterm="sql-createtable-storage-parameters-title"> for more - information. The <literal>WITH</> clause - can also include <literal>OIDS=TRUE</> (or just <literal>OIDS</>) + information. The <literal>WITH</literal> clause + can also include <literal>OIDS=TRUE</literal> (or just <literal>OIDS</literal>) to specify that rows of the new table should have OIDs (object identifiers) assigned to them, or - <literal>OIDS=FALSE</> to specify that the rows should not have OIDs. + <literal>OIDS=FALSE</literal> to specify that the rows should not have OIDs. See <xref linkend="sql-createtable"> for more information. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>WITH OIDS</></term> - <term><literal>WITHOUT OIDS</></term> + <term><literal>WITH OIDS</literal></term> + <term><literal>WITHOUT OIDS</literal></term> <listitem> <para> - These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</> - and <literal>WITH (OIDS=FALSE)</>, respectively. If you wish to give - both an <literal>OIDS</> setting and storage parameters, you must use - the <literal>WITH ( ... )</> syntax; see above. + These are obsolescent syntaxes equivalent to <literal>WITH (OIDS)</literal> + and <literal>WITH (OIDS=FALSE)</literal>, respectively. If you wish to give + both an <literal>OIDS</literal> setting and storage parameters, you must use + the <literal>WITH ( ... )</literal> syntax; see above. </para> </listitem> </varlistentry> @@ -214,14 +214,14 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI A <xref linkend="sql-select">, <link linkend="sql-table">TABLE</link>, or <xref linkend="sql-values"> command, or an <xref linkend="sql-execute"> command that runs a - prepared <command>SELECT</>, <command>TABLE</>, or - <command>VALUES</> query. + prepared <command>SELECT</command>, <command>TABLE</command>, or + <command>VALUES</command> query. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>WITH [ NO ] DATA</></term> + <term><literal>WITH [ NO ] DATA</literal></term> <listitem> <para> This clause specifies whether or not the data produced by the query @@ -241,7 +241,7 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI This command is functionally similar to <xref linkend="sql-selectinto">, but it is preferred since it is less likely to be confused with other uses of - the <command>SELECT INTO</> syntax. Furthermore, <command>CREATE + the <command>SELECT INTO</command> syntax. Furthermore, <command>CREATE TABLE AS</command> offers a superset of the functionality offered by <command>SELECT INTO</command>. </para> @@ -315,7 +315,7 @@ CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS </listitem> <listitem> - <para><productname>PostgreSQL</> handles temporary tables in a way + <para><productname>PostgreSQL</productname> handles temporary tables in a way rather different from the standard; see <xref linkend="sql-createtable"> for details. @@ -324,7 +324,7 @@ CREATE TEMP TABLE films_recent WITH (OIDS) ON COMMIT DROP AS <listitem> <para> - The <literal>WITH</> clause is a <productname>PostgreSQL</productname> + The <literal>WITH</literal> clause is a <productname>PostgreSQL</productname> extension; neither storage parameters nor OIDs are in the standard. </para> </listitem> diff --git a/doc/src/sgml/ref/create_tablespace.sgml b/doc/src/sgml/ref/create_tablespace.sgml index 2fed29ffaf3..4d95cac9e59 100644 --- a/doc/src/sgml/ref/create_tablespace.sgml +++ b/doc/src/sgml/ref/create_tablespace.sgml @@ -45,9 +45,9 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <para> A user with appropriate privileges can pass - <replaceable class="parameter">tablespace_name</> to - <command>CREATE DATABASE</>, <command>CREATE TABLE</>, - <command>CREATE INDEX</> or <command>ADD CONSTRAINT</> to have the data + <replaceable class="parameter">tablespace_name</replaceable> to + <command>CREATE DATABASE</command>, <command>CREATE TABLE</command>, + <command>CREATE INDEX</command> or <command>ADD CONSTRAINT</command> to have the data files for these objects stored within the specified tablespace. </para> @@ -93,7 +93,7 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <para> The directory that will be used for the tablespace. The directory should be empty and must be owned by the - <productname>PostgreSQL</> system user. The directory must be + <productname>PostgreSQL</productname> system user. The directory must be specified by an absolute path name. </para> </listitem> @@ -104,8 +104,8 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <listitem> <para> A tablespace parameter to be set or reset. Currently, the only - available parameters are <varname>seq_page_cost</>, - <varname>random_page_cost</> and <varname>effective_io_concurrency</>. + available parameters are <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname> and <varname>effective_io_concurrency</varname>. Setting either value for a particular tablespace will override the planner's usual estimate of the cost of reading pages from tables in that tablespace, as established by the configuration parameters of the @@ -128,7 +128,7 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> </para> <para> - <command>CREATE TABLESPACE</> cannot be executed inside a transaction + <command>CREATE TABLESPACE</command> cannot be executed inside a transaction block. </para> </refsect1> @@ -137,15 +137,15 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> <title>Examples</title> <para> - Create a tablespace <literal>dbspace</> at <literal>/data/dbs</>: + Create a tablespace <literal>dbspace</literal> at <literal>/data/dbs</literal>: <programlisting> CREATE TABLESPACE dbspace LOCATION '/data/dbs'; </programlisting> </para> <para> - Create a tablespace <literal>indexspace</> at <literal>/data/indexes</> - owned by user <literal>genevieve</>: + Create a tablespace <literal>indexspace</literal> at <literal>/data/indexes</literal> + owned by user <literal>genevieve</literal>: <programlisting> CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes'; </programlisting></para> @@ -155,7 +155,7 @@ CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes'; <title>Compatibility</title> <para> - <command>CREATE TABLESPACE</command> is a <productname>PostgreSQL</> + <command>CREATE TABLESPACE</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml index 7fc481d9fcc..6726e3c7663 100644 --- a/doc/src/sgml/ref/create_trigger.sgml +++ b/doc/src/sgml/ref/create_trigger.sgml @@ -86,10 +86,10 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </para> <para> - Triggers that are specified to fire <literal>INSTEAD OF</> the trigger - event must be marked <literal>FOR EACH ROW</>, and can only be defined - on views. <literal>BEFORE</> and <literal>AFTER</> triggers on a view - must be marked as <literal>FOR EACH STATEMENT</>. + Triggers that are specified to fire <literal>INSTEAD OF</literal> the trigger + event must be marked <literal>FOR EACH ROW</literal>, and can only be defined + on views. <literal>BEFORE</literal> and <literal>AFTER</literal> triggers on a view + must be marked as <literal>FOR EACH STATEMENT</literal>. </para> <para> @@ -115,35 +115,35 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </thead> <tbody> <row> - <entry align="center" morerows="1"><literal>BEFORE</></entry> - <entry align="center"><command>INSERT</>/<command>UPDATE</>/<command>DELETE</></entry> + <entry align="center" morerows="1"><literal>BEFORE</literal></entry> + <entry align="center"><command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command></entry> <entry align="center">Tables and foreign tables</entry> <entry align="center">Tables, views, and foreign tables</entry> </row> <row> - <entry align="center"><command>TRUNCATE</></entry> + <entry align="center"><command>TRUNCATE</command></entry> <entry align="center">—</entry> <entry align="center">Tables</entry> </row> <row> - <entry align="center" morerows="1"><literal>AFTER</></entry> - <entry align="center"><command>INSERT</>/<command>UPDATE</>/<command>DELETE</></entry> + <entry align="center" morerows="1"><literal>AFTER</literal></entry> + <entry align="center"><command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command></entry> <entry align="center">Tables and foreign tables</entry> <entry align="center">Tables, views, and foreign tables</entry> </row> <row> - <entry align="center"><command>TRUNCATE</></entry> + <entry align="center"><command>TRUNCATE</command></entry> <entry align="center">—</entry> <entry align="center">Tables</entry> </row> <row> - <entry align="center" morerows="1"><literal>INSTEAD OF</></entry> - <entry align="center"><command>INSERT</>/<command>UPDATE</>/<command>DELETE</></entry> + <entry align="center" morerows="1"><literal>INSTEAD OF</literal></entry> + <entry align="center"><command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command></entry> <entry align="center">Views</entry> <entry align="center">—</entry> </row> <row> - <entry align="center"><command>TRUNCATE</></entry> + <entry align="center"><command>TRUNCATE</command></entry> <entry align="center">—</entry> <entry align="center">—</entry> </row> @@ -152,11 +152,11 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </informaltable> <para> - Also, a trigger definition can specify a Boolean <literal>WHEN</> + Also, a trigger definition can specify a Boolean <literal>WHEN</literal> condition, which will be tested to see whether the trigger should - be fired. In row-level triggers the <literal>WHEN</> condition can + be fired. In row-level triggers the <literal>WHEN</literal> condition can examine the old and/or new values of columns of the row. Statement-level - triggers can also have <literal>WHEN</> conditions, although the feature + triggers can also have <literal>WHEN</literal> conditions, although the feature is not so useful for them since the condition cannot refer to any values in the table. </para> @@ -167,36 +167,36 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> </para> <para> - When the <literal>CONSTRAINT</> option is specified, this command creates a - <firstterm>constraint trigger</>. This is the same as a regular trigger + When the <literal>CONSTRAINT</literal> option is specified, this command creates a + <firstterm>constraint trigger</firstterm>. This is the same as a regular trigger except that the timing of the trigger firing can be adjusted using <xref linkend="SQL-SET-CONSTRAINTS">. - Constraint triggers must be <literal>AFTER ROW</> triggers on plain + Constraint triggers must be <literal>AFTER ROW</literal> 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 <firstterm>deferred</>. A pending deferred-trigger firing + are said to be <firstterm>deferred</firstterm>. A pending deferred-trigger firing can also be forced to happen immediately by using <command>SET - CONSTRAINTS</>. Constraint triggers are expected to raise an exception + CONSTRAINTS</command>. Constraint triggers are expected to raise an exception when the constraints they implement are violated. </para> <para> - The <literal>REFERENCING</> option enables collection - of <firstterm>transition relations</>, which are row sets that include all + The <literal>REFERENCING</literal> option enables collection + of <firstterm>transition relations</firstterm>, 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 <literal>AFTER</> trigger that is not a constraint trigger; also, if - the trigger is an <literal>UPDATE</> trigger, it must not specify + an <literal>AFTER</literal> trigger that is not a constraint trigger; also, if + the trigger is an <literal>UPDATE</literal> trigger, it must not specify a <replaceable class="parameter">column_name</replaceable> list. - <literal>OLD TABLE</> may only be specified once, and only for a trigger - that can fire on <literal>UPDATE</> or <literal>DELETE</>; it creates a - transition relation containing the <firstterm>before-images</> of all rows + <literal>OLD TABLE</literal> may only be specified once, and only for a trigger + that can fire on <literal>UPDATE</literal> or <literal>DELETE</literal>; it creates a + transition relation containing the <firstterm>before-images</firstterm> of all rows updated or deleted by the statement. - Similarly, <literal>NEW TABLE</> may only be specified once, and only for - a trigger that can fire on <literal>UPDATE</> or <literal>INSERT</>; - it creates a transition relation containing the <firstterm>after-images</> + Similarly, <literal>NEW TABLE</literal> may only be specified once, and only for + a trigger that can fire on <literal>UPDATE</literal> or <literal>INSERT</literal>; + it creates a transition relation containing the <firstterm>after-images</firstterm> of all rows updated or inserted by the statement. </para> @@ -225,7 +225,7 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> The name cannot be schema-qualified — the trigger inherits the schema of its table. For a constraint trigger, this is also the name to use when modifying the trigger's behavior using - <command>SET CONSTRAINTS</>. + <command>SET CONSTRAINTS</command>. </para> </listitem> </varlistentry> @@ -238,7 +238,7 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> <para> Determines whether the function is called before, after, or instead of the event. A constraint trigger can only be specified as - <literal>AFTER</>. + <literal>AFTER</literal>. </para> </listitem> </varlistentry> @@ -261,11 +261,11 @@ CREATE [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</replaceable> ... ] </synopsis> The trigger will only fire if at least one of the listed columns - is mentioned as a target of the <command>UPDATE</> command. + is mentioned as a target of the <command>UPDATE</command> command. </para> <para> - <literal>INSTEAD OF UPDATE</> events do not allow a list of columns. + <literal>INSTEAD OF UPDATE</literal> events do not allow a list of columns. A column list cannot be specified when requesting transition relations, either. </para> @@ -352,7 +352,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ once for every row affected by the trigger event, or just once per SQL statement. If neither is specified, <literal>FOR EACH STATEMENT</literal> is the default. Constraint triggers can only - be specified <literal>FOR EACH ROW</>. + be specified <literal>FOR EACH ROW</literal>. </para> </listitem> </varlistentry> @@ -362,20 +362,20 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <listitem> <para> A Boolean expression that determines whether the trigger function - will actually be executed. If <literal>WHEN</> is specified, the + will actually be executed. If <literal>WHEN</literal> is specified, the function will only be called if the <replaceable - class="parameter">condition</replaceable> returns <literal>true</>. - In <literal>FOR EACH ROW</literal> triggers, the <literal>WHEN</> + class="parameter">condition</replaceable> returns <literal>true</literal>. + In <literal>FOR EACH ROW</literal> triggers, the <literal>WHEN</literal> condition can refer to columns of the old and/or new row values by writing <literal>OLD.<replaceable class="parameter">column_name</replaceable></literal> or <literal>NEW.<replaceable class="parameter">column_name</replaceable></literal> respectively. - Of course, <literal>INSERT</> triggers cannot refer to <literal>OLD</> - and <literal>DELETE</> triggers cannot refer to <literal>NEW</>. + Of course, <literal>INSERT</literal> triggers cannot refer to <literal>OLD</literal> + and <literal>DELETE</literal> triggers cannot refer to <literal>NEW</literal>. </para> - <para><literal>INSTEAD OF</> triggers do not support <literal>WHEN</> + <para><literal>INSTEAD OF</literal> triggers do not support <literal>WHEN</literal> conditions. </para> @@ -385,7 +385,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ </para> <para> - Note that for constraint triggers, evaluation of the <literal>WHEN</> + Note that for constraint triggers, evaluation of the <literal>WHEN</literal> 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. @@ -398,7 +398,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <listitem> <para> A user-supplied function that is declared as taking no arguments - and returning type <literal>trigger</>, which is executed when + and returning type <literal>trigger</literal>, which is executed when the trigger fires. </para> </listitem> @@ -438,32 +438,32 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> A column-specific trigger (one defined using the <literal>UPDATE OF <replaceable>column_name</replaceable></literal> syntax) will fire when any - of its columns are listed as targets in the <command>UPDATE</> - command's <literal>SET</> list. It is possible for a column's value + of its columns are listed as targets in the <command>UPDATE</command> + command's <literal>SET</literal> list. It is possible for a column's value to change even when the trigger is not fired, because changes made to the - row's contents by <literal>BEFORE UPDATE</> triggers are not considered. - Conversely, a command such as <literal>UPDATE ... SET x = x ...</> - will fire a trigger on column <literal>x</>, even though the column's + row's contents by <literal>BEFORE UPDATE</literal> triggers are not considered. + Conversely, a command such as <literal>UPDATE ... SET x = x ...</literal> + will fire a trigger on column <literal>x</literal>, even though the column's value did not change. </para> <para> - In a <literal>BEFORE</> trigger, the <literal>WHEN</> condition is + In a <literal>BEFORE</literal> trigger, the <literal>WHEN</literal> condition is evaluated just before the function is or would be executed, so using - <literal>WHEN</> is not materially different from testing the same + <literal>WHEN</literal> is not materially different from testing the same condition at the beginning of the trigger function. Note in particular - that the <literal>NEW</> row seen by the condition is the current value, - as possibly modified by earlier triggers. Also, a <literal>BEFORE</> - trigger's <literal>WHEN</> condition is not allowed to examine the - system columns of the <literal>NEW</> row (such as <literal>oid</>), + that the <literal>NEW</literal> row seen by the condition is the current value, + as possibly modified by earlier triggers. Also, a <literal>BEFORE</literal> + trigger's <literal>WHEN</literal> condition is not allowed to examine the + system columns of the <literal>NEW</literal> row (such as <literal>oid</literal>), because those won't have been set yet. </para> <para> - In an <literal>AFTER</> trigger, the <literal>WHEN</> condition is + In an <literal>AFTER</literal> trigger, the <literal>WHEN</literal> 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 - <literal>AFTER</> trigger's <literal>WHEN</> condition does not return + <literal>AFTER</literal> trigger's <literal>WHEN</literal> 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 @@ -473,7 +473,7 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> In some cases it is possible for a single SQL command to fire more than one kind of trigger. For instance an <command>INSERT</command> with - an <literal>ON CONFLICT DO UPDATE</> clause may cause both insert and + an <literal>ON CONFLICT DO UPDATE</literal> 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 <command>INSERT</command> trigger @@ -483,14 +483,14 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> Row updates or deletions caused by foreign-key enforcement actions, such - as <literal>ON UPDATE CASCADE</> or <literal>ON DELETE SET NULL</>, are + as <literal>ON UPDATE CASCADE</literal> or <literal>ON DELETE SET NULL</literal>, 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 a 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 <literal>AFTER ROW</> + However, there are cases in which the presence of an <literal>AFTER ROW</literal> 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, @@ -516,10 +516,10 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <para> In <productname>PostgreSQL</productname> versions before 7.3, it was necessary to declare trigger functions as returning the placeholder - type <type>opaque</>, rather than <type>trigger</>. To support loading - of old dump files, <command>CREATE TRIGGER</> will accept a function - declared as returning <type>opaque</>, but it will issue a notice and - change the function's declared return type to <type>trigger</>. + type <type>opaque</type>, rather than <type>trigger</type>. To support loading + of old dump files, <command>CREATE TRIGGER</command> will accept a function + declared as returning <type>opaque</type>, but it will issue a notice and + change the function's declared return type to <type>trigger</type>. </para> </refsect1> @@ -527,8 +527,8 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</ <title>Examples</title> <para> - Execute the function <function>check_account_update</> whenever - a row of the table <literal>accounts</> is about to be updated: + Execute the function <function>check_account_update</function> whenever + a row of the table <literal>accounts</literal> is about to be updated: <programlisting> CREATE TRIGGER check_update @@ -537,8 +537,8 @@ CREATE TRIGGER check_update EXECUTE PROCEDURE check_account_update(); </programlisting> - The same, but only execute the function if column <literal>balance</> - is specified as a target in the <command>UPDATE</> command: + The same, but only execute the function if column <literal>balance</literal> + is specified as a target in the <command>UPDATE</command> command: <programlisting> CREATE TRIGGER check_update @@ -547,7 +547,7 @@ CREATE TRIGGER check_update EXECUTE PROCEDURE check_account_update(); </programlisting> - This form only executes the function if column <literal>balance</> + This form only executes the function if column <literal>balance</literal> has in fact changed value: <programlisting> @@ -558,7 +558,7 @@ CREATE TRIGGER check_update EXECUTE PROCEDURE check_account_update(); </programlisting> - Call a function to log updates of <literal>accounts</>, but only if + Call a function to log updates of <literal>accounts</literal>, but only if something changed: <programlisting> @@ -569,7 +569,7 @@ CREATE TRIGGER log_update EXECUTE PROCEDURE log_account_update(); </programlisting> - Execute the function <function>view_insert_row</> for each row to insert + Execute the function <function>view_insert_row</function> for each row to insert rows into the tables underlying a view: <programlisting> @@ -579,8 +579,8 @@ CREATE TRIGGER view_insert EXECUTE PROCEDURE view_insert_row(); </programlisting> - Execute the function <function>check_transfer_balances_to_zero</> for each - statement to confirm that the <literal>transfer</> rows offset to a net of + Execute the function <function>check_transfer_balances_to_zero</function> for each + statement to confirm that the <literal>transfer</literal> rows offset to a net of zero: <programlisting> @@ -591,7 +591,7 @@ CREATE TRIGGER transfer_insert EXECUTE PROCEDURE check_transfer_balances_to_zero(); </programlisting> - Execute the function <function>check_matching_pairs</> for each row to + Execute the function <function>check_matching_pairs</function> for each row to confirm that changes are made to matching pairs at the same time (by the same statement): @@ -624,27 +624,27 @@ CREATE TRIGGER paired_items_update <para> The <command>CREATE TRIGGER</command> statement in <productname>PostgreSQL</productname> implements a subset of the - <acronym>SQL</> standard. The following functionalities are currently + <acronym>SQL</acronym> standard. The following functionalities are currently missing: <itemizedlist> <listitem> <para> - While transition table names for <literal>AFTER</> triggers are - specified using the <literal>REFERENCING</> clause in the standard way, - the row variables used in <literal>FOR EACH ROW</> triggers may not be - specified in a <literal>REFERENCING</> clause. They are available in a + While transition table names for <literal>AFTER</literal> triggers are + specified using the <literal>REFERENCING</literal> clause in the standard way, + the row variables used in <literal>FOR EACH ROW</literal> triggers may not be + specified in a <literal>REFERENCING</literal> 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 <literal>REFERENCING</> clause - containing <literal>OLD ROW AS OLD NEW ROW AS NEW</>. + effectively behave as though there is a <literal>REFERENCING</literal> clause + containing <literal>OLD ROW AS OLD NEW ROW AS NEW</literal>. </para> </listitem> <listitem> <para> The standard allows transition tables to be used with - column-specific <literal>UPDATE</> triggers, but then the set of rows + column-specific <literal>UPDATE</literal> triggers, but then the set of rows that should be visible in the transition tables depends on the trigger's column list. This is not currently implemented by <productname>PostgreSQL</productname>. @@ -673,7 +673,7 @@ CREATE TRIGGER paired_items_update <para> SQL specifies that <literal>BEFORE DELETE</literal> triggers on cascaded - deletes fire <emphasis>after</> the cascaded <literal>DELETE</> completes. + deletes fire <emphasis>after</emphasis> the cascaded <literal>DELETE</literal> completes. The <productname>PostgreSQL</productname> behavior is for <literal>BEFORE DELETE</literal> to always fire before the delete action, even a cascading one. This is considered more consistent. There is also nonstandard @@ -685,19 +685,19 @@ CREATE TRIGGER paired_items_update <para> The ability to specify multiple actions for a single trigger using - <literal>OR</literal> is a <productname>PostgreSQL</> extension of + <literal>OR</literal> is a <productname>PostgreSQL</productname> extension of the SQL standard. </para> <para> The ability to fire triggers for <command>TRUNCATE</command> is a - <productname>PostgreSQL</> extension of the SQL standard, as is the + <productname>PostgreSQL</productname> extension of the SQL standard, as is the ability to define statement-level triggers on views. </para> <para> <command>CREATE CONSTRAINT TRIGGER</command> is a - <productname>PostgreSQL</productname> extension of the <acronym>SQL</> + <productname>PostgreSQL</productname> extension of the <acronym>SQL</acronym> standard. </para> diff --git a/doc/src/sgml/ref/create_tsconfig.sgml b/doc/src/sgml/ref/create_tsconfig.sgml index 63321520df2..d1792e5d29d 100644 --- a/doc/src/sgml/ref/create_tsconfig.sgml +++ b/doc/src/sgml/ref/create_tsconfig.sgml @@ -99,7 +99,7 @@ CREATE TEXT SEARCH CONFIGURATION <replaceable class="parameter">name</replaceabl <title>Notes</title> <para> - The <literal>PARSER</> and <literal>COPY</> options are mutually + The <literal>PARSER</literal> and <literal>COPY</literal> options are mutually exclusive, because when an existing configuration is copied, its parser selection is copied too. </para> diff --git a/doc/src/sgml/ref/create_tstemplate.sgml b/doc/src/sgml/ref/create_tstemplate.sgml index 360ad41f354..e10f18b28b8 100644 --- a/doc/src/sgml/ref/create_tstemplate.sgml +++ b/doc/src/sgml/ref/create_tstemplate.sgml @@ -49,7 +49,7 @@ CREATE TEXT SEARCH TEMPLATE <replaceable class="parameter">name</replaceable> ( TEMPLATE</command>. 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 <quote>unsafe</> aspects of defining a dictionary. + encapsulates the <quote>unsafe</quote> 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. diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 312bd050bc3..02ca27b281e 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -81,8 +81,8 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> There are five forms of <command>CREATE TYPE</command>, as shown in the syntax synopsis above. They respectively create a <firstterm>composite - type</>, an <firstterm>enum type</>, a <firstterm>range type</>, a - <firstterm>base type</>, or a <firstterm>shell type</>. The first four + type</firstterm>, an <firstterm>enum type</firstterm>, a <firstterm>range type</firstterm>, a + <firstterm>base type</firstterm>, or a <firstterm>shell type</firstterm>. 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 <command>CREATE TYPE</command> with no parameters except for the type name. Shell types @@ -154,7 +154,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 <literal>CREATE TYPE - <replaceable>name</></literal>, with no additional parameters. Then + <replaceable>name</replaceable></literal>, 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. @@ -211,7 +211,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> The first argument is the input text as a C string, the second argument is the type's own OID (except for array types, which instead receive their element type's OID), - and the third is the <literal>typmod</> of the destination column, if known + and the third is the <literal>typmod</literal> 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, @@ -264,12 +264,12 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 <firstterm>shell type</>, which is a + the type should first be defined as a <firstterm>shell type</firstterm>, which is a placeholder type that has no properties except a name and an owner. This is done by issuing the command <literal>CREATE TYPE - <replaceable>name</></literal>, with no additional parameters. Then the + <replaceable>name</replaceable></literal>, with no additional parameters. Then the C I/O functions can be defined referencing the shell type. Finally, - <command>CREATE TYPE</> with a full definition replaces the shell entry + <command>CREATE TYPE</command> with a full definition replaces the shell entry with a complete, valid type definition, after which the new type can be used normally. </para> @@ -279,23 +279,23 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">type_modifier_input_function</replaceable> and <replaceable class="parameter">type_modifier_output_function</replaceable> are needed if the type supports modifiers, that is optional constraints - attached to a type declaration, such as <literal>char(5)</> or - <literal>numeric(30,2)</>. <productname>PostgreSQL</productname> allows + attached to a type declaration, such as <literal>char(5)</literal> or + <literal>numeric(30,2)</literal>. <productname>PostgreSQL</productname> 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 <replaceable class="parameter">type_modifier_input_function</replaceable> - is passed the declared modifier(s) in the form of a <type>cstring</> + is passed the declared modifier(s) in the form of a <type>cstring</type> 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 - <type>integer</> value that will be stored as the column <quote>typmod</>. + <type>integer</type> value that will be stored as the column <quote>typmod</quote>. Type modifiers will be rejected if the type does not have a <replaceable class="parameter">type_modifier_input_function</replaceable>. The <replaceable class="parameter">type_modifier_output_function</replaceable> converts the internal integer typmod value back to the correct form for - user display. It must return a <type>cstring</> value that is the exact - string to append to the type name; for example <type>numeric</>'s - function might return <literal>(30,2)</>. + user display. It must return a <type>cstring</type> value that is the exact + string to append to the type name; for example <type>numeric</type>'s + function might return <literal>(30,2)</literal>. It is allowed to omit the <replaceable class="parameter">type_modifier_output_function</replaceable>, in which case the default display format is just the stored typmod integer @@ -305,14 +305,14 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> The optional <replaceable class="parameter">analyze_function</replaceable> performs type-specific statistics collection for columns of the data type. - By default, <command>ANALYZE</> will attempt to gather statistics using - the type's <quote>equals</> and <quote>less-than</> operators, if there + By default, <command>ANALYZE</command> will attempt to gather statistics using + the type's <quote>equals</quote> and <quote>less-than</quote> 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 <type>internal</>, and return - a <type>boolean</> result. The detailed API for analysis functions appears - in <filename>src/include/commands/vacuum.h</>. + declared to take a single argument of type <type>internal</type>, and return + a <type>boolean</type> result. The detailed API for analysis functions appears + in <filename>src/include/commands/vacuum.h</filename>. </para> <para> @@ -327,7 +327,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> positive integer, or variable-length, indicated by setting <replaceable class="parameter">internallength</replaceable> to <literal>VARIABLE</literal>. (Internally, this is represented - by setting <literal>typlen</> to -1.) The internal representation of all + by setting <literal>typlen</literal> 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 <xref linkend="storage-toast">; it's unwise @@ -338,7 +338,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> The optional flag <literal>PASSEDBYVALUE</literal> 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 <type>Datum</> type + representation cannot be larger than the size of the <type>Datum</type> type (4 bytes on some machines, 8 bytes on others). </para> @@ -347,7 +347,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 <type>int4</> as their first component. + 4, since they necessarily contain an <type>int4</type> as their first component. </para> <para> @@ -372,12 +372,12 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> All <replaceable class="parameter">storage</replaceable> values other than <literal>plain</literal> imply that the functions of the data type - can handle values that have been <firstterm>toasted</>, as described + can handle values that have been <firstterm>toasted</firstterm>, as described in <xref linkend="storage-toast"> and <xref linkend="xtypes-toast">. 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 <literal>ALTER TABLE - SET STORAGE</>. + SET STORAGE</literal>. </para> <para> @@ -389,9 +389,9 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">alignment</replaceable>, and <replaceable class="parameter">storage</replaceable> are copied from the named type. (It is possible, though usually undesirable, to override - some of these values by specifying them along with the <literal>LIKE</> + some of these values by specifying them along with the <literal>LIKE</literal> clause.) Specifying representation this way is especially useful when - the low-level implementation of the new type <quote>piggybacks</> on an + the low-level implementation of the new type <quote>piggybacks</quote> on an existing type in some fashion. </para> @@ -400,7 +400,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">preferred</replaceable> 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 <quote>preferred</> or not within its + character, and each type is either <quote>preferred</quote> 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 <xref @@ -408,7 +408,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 <quote>most general</> types as being preferred within the category. + of the <quote>most general</quote> types as being preferred within the category. The <replaceable class="parameter">category</replaceable> 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 @@ -426,7 +426,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> To indicate that a type is an array, specify the type of the array - elements using the <literal>ELEMENT</> key word. For example, to + elements using the <literal>ELEMENT</literal> key word. For example, to define an array of 4-byte integers (<type>int4</type>), specify <literal>ELEMENT = int4</literal>. More details about array types appear below. @@ -465,26 +465,26 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 <literal>array_in</> and - <literal>array_out</>. The array type tracks any changes in its + built-in input and output functions <literal>array_in</literal> and + <literal>array_out</literal>. The array type tracks any changes in its element type's owner or schema, and is dropped if the element type is. </para> <para> - You might reasonably ask why there is an <option>ELEMENT</> + You might reasonably ask why there is an <option>ELEMENT</option> option, if the system makes the correct array type automatically. - The only case where it's useful to use <option>ELEMENT</> is when you are + The only case where it's useful to use <option>ELEMENT</option> 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 <type>point</> + to provide for the type as a whole. For example, type <type>point</type> is represented as just two floating-point numbers, which can be accessed - using <literal>point[0]</> and <literal>point[1]</>. + using <literal>point[0]</literal> and <literal>point[1]</literal>. Note that this facility only works for fixed-length types whose internal form is exactly a sequence of identical fixed-length fields. A subscriptable variable-length type must have the generalized internal representation - used by <literal>array_in</> and <literal>array_out</>. + used by <literal>array_in</literal> and <literal>array_out</literal>. For historical reasons (i.e., this is clearly wrong but it's far too late to change it), subscripting of fixed-length array types starts from zero, rather than from one as for variable-length arrays. @@ -697,7 +697,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <replaceable class="parameter">alignment</replaceable>, and <replaceable class="parameter">storage</replaceable> are copied from that type, unless overridden by explicit - specification elsewhere in this <command>CREATE TYPE</> command. + specification elsewhere in this <command>CREATE TYPE</command> command. </para> </listitem> </varlistentry> @@ -707,7 +707,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <listitem> <para> The category code (a single ASCII character) for this type. - The default is <literal>'U'</> for <quote>user-defined type</>. + The default is <literal>'U'</literal> for <quote>user-defined type</quote>. Other standard category codes can be found in <xref linkend="catalog-typcategory-table">. You may also choose other ASCII characters in order to create custom categories. @@ -779,7 +779,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 <quote>secret</> information to be used + in a way that would require <quote>secret</quote> information to be used while converting it to or from external form. </para> @@ -792,7 +792,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> 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 - <structname>pg_type</>.<structfield>typarray</> to locate the array type + <structname>pg_type</structname>.<structfield>typarray</structfield> to locate the array type associated with a given type. </para> @@ -807,7 +807,7 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> <para> Before <productname>PostgreSQL</productname> version 8.2, the shell-type creation syntax - <literal>CREATE TYPE <replaceable>name</></literal> did not exist. + <literal>CREATE TYPE <replaceable>name</replaceable></literal> did not exist. The way to create a new base type was to create its input function first. In this approach, <productname>PostgreSQL</productname> will first see the name of the new data type as the return type of the input function. @@ -824,10 +824,10 @@ CREATE TYPE <replaceable class="parameter">name</replaceable> In <productname>PostgreSQL</productname> versions before 7.3, it was customary to avoid creating a shell type at all, by replacing the functions' forward references to the type name with the placeholder - pseudo-type <type>opaque</>. The <type>cstring</> arguments and - results also had to be declared as <type>opaque</> before 7.3. To - support loading of old dump files, <command>CREATE TYPE</> will - accept I/O functions declared using <type>opaque</>, but it will issue + pseudo-type <type>opaque</type>. The <type>cstring</type> arguments and + results also had to be declared as <type>opaque</type> before 7.3. To + support loading of old dump files, <command>CREATE TYPE</command> will + accept I/O functions declared using <type>opaque</type>, but it will issue a notice and change the function declarations to use the correct types. </para> @@ -894,7 +894,7 @@ CREATE TABLE myboxes ( <para> If the internal structure of <type>box</type> were an array of four - <type>float4</> elements, we might instead use: + <type>float4</type> elements, we might instead use: <programlisting> CREATE TYPE box ( INTERNALLENGTH = 16, @@ -933,11 +933,11 @@ CREATE TABLE big_objs ( <para> The first form of the <command>CREATE TYPE</command> command, which - creates a composite type, conforms to the <acronym>SQL</> standard. + creates a composite type, conforms to the <acronym>SQL</acronym> standard. The other forms are <productname>PostgreSQL</productname> extensions. The <command>CREATE TYPE</command> statement in - the <acronym>SQL</> standard also defines other forms that are not - implemented in <productname>PostgreSQL</>. + the <acronym>SQL</acronym> standard also defines other forms that are not + implemented in <productname>PostgreSQL</productname>. </para> <para> diff --git a/doc/src/sgml/ref/create_user.sgml b/doc/src/sgml/ref/create_user.sgml index 480b6405e6b..500169da986 100644 --- a/doc/src/sgml/ref/create_user.sgml +++ b/doc/src/sgml/ref/create_user.sgml @@ -51,8 +51,8 @@ CREATE USER <replaceable class="parameter">name</replaceable> [ [ WITH ] <replac <command>CREATE USER</command> is now an alias for <xref linkend="sql-createrole">. The only difference is that when the command is spelled - <command>CREATE USER</command>, <literal>LOGIN</> is assumed - by default, whereas <literal>NOLOGIN</> is assumed when + <command>CREATE USER</command>, <literal>LOGIN</literal> is assumed + by default, whereas <literal>NOLOGIN</literal> is assumed when the command is spelled <command>CREATE ROLE</command>. </para> diff --git a/doc/src/sgml/ref/create_user_mapping.sgml b/doc/src/sgml/ref/create_user_mapping.sgml index d6f29c94893..10182e14266 100644 --- a/doc/src/sgml/ref/create_user_mapping.sgml +++ b/doc/src/sgml/ref/create_user_mapping.sgml @@ -41,7 +41,7 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <para> 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 <literal>USAGE</> privilege on the server has + their own user name if <literal>USAGE</literal> privilege on the server has been granted to the user. </para> </refsect1> @@ -51,7 +51,7 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <variablelist> <varlistentry> - <term><literal>IF NOT EXISTS</></term> + <term><literal>IF NOT EXISTS</literal></term> <listitem> <para> Do not throw an error if a mapping of the given user to the given foreign @@ -67,8 +67,8 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <listitem> <para> The name of an existing user that is mapped to foreign server. - <literal>CURRENT_USER</> and <literal>USER</> match the name of - the current user. When <literal>PUBLIC</> is specified, a + <literal>CURRENT_USER</literal> and <literal>USER</literal> match the name of + the current user. When <literal>PUBLIC</literal> is specified, a so-called public mapping is created that is used when no user-specific mapping is applicable. </para> @@ -103,7 +103,7 @@ CREATE USER MAPPING [IF NOT EXISTS] FOR { <replaceable class="parameter">user_na <title>Examples</title> <para> - Create a user mapping for user <literal>bob</>, server <literal>foo</>: + Create a user mapping for user <literal>bob</literal>, server <literal>foo</literal>: <programlisting> CREATE USER MAPPING FOR bob SERVER foo OPTIONS (user 'bob', password 'secret'); </programlisting></para> diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml index 695c7593120..c0dd0224955 100644 --- a/doc/src/sgml/ref/create_view.sgml +++ b/doc/src/sgml/ref/create_view.sgml @@ -48,7 +48,7 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class <para> If a schema name is given (for example, <literal>CREATE VIEW - myschema.myview ...</>) then the view is created in the specified + myschema.myview ...</literal>) 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 @@ -62,7 +62,7 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class <variablelist> <varlistentry> - <term><literal>TEMPORARY</> or <literal>TEMP</></term> + <term><literal>TEMPORARY</literal> or <literal>TEMP</literal></term> <listitem> <para> If specified, the view is created as a temporary view. @@ -82,16 +82,16 @@ CREATE [ OR REPLACE ] [ TEMP | TEMPORARY ] [ RECURSIVE ] VIEW <replaceable class </varlistentry> <varlistentry> - <term><literal>RECURSIVE</></term> + <term><literal>RECURSIVE</literal></term> <listitem> <para> Creates a recursive view. The syntax <synopsis> -CREATE RECURSIVE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> (<replaceable>column_names</>) AS SELECT <replaceable>...</>; +CREATE RECURSIVE VIEW [ <replaceable>schema</replaceable> . ] <replaceable>view_name</replaceable> (<replaceable>column_names</replaceable>) AS SELECT <replaceable>...</replaceable>; </synopsis> is equivalent to <synopsis> -CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECURSIVE <replaceable>view_name</> (<replaceable>column_names</>) AS (SELECT <replaceable>...</>) SELECT <replaceable>column_names</> FROM <replaceable>view_name</>; +CREATE VIEW [ <replaceable>schema</replaceable> . ] <replaceable>view_name</replaceable> AS WITH RECURSIVE <replaceable>view_name</replaceable> (<replaceable>column_names</replaceable>) AS (SELECT <replaceable>...</replaceable>) SELECT <replaceable>column_names</replaceable> FROM <replaceable>view_name</replaceable>; </synopsis> A view column name list must be specified for a recursive view. </para> @@ -129,9 +129,9 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <term><literal>check_option</literal> (<type>string</type>)</term> <listitem> <para> - This parameter may be either <literal>local</> or - <literal>cascaded</>, and is equivalent to specifying - <literal>WITH [ CASCADED | LOCAL ] CHECK OPTION</> (see below). + This parameter may be either <literal>local</literal> or + <literal>cascaded</literal>, and is equivalent to specifying + <literal>WITH [ CASCADED | LOCAL ] CHECK OPTION</literal> (see below). This option can be changed on existing views using <xref linkend="sql-alterview">. </para> @@ -175,12 +175,12 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <listitem> <para> This option controls the behavior of automatically updatable views. When - this option is specified, <command>INSERT</> and <command>UPDATE</> + this option is specified, <command>INSERT</command> and <command>UPDATE</command> 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 <literal>CHECK OPTION</> is not specified, - <command>INSERT</> and <command>UPDATE</> commands on the view are + rejected. If the <literal>CHECK OPTION</literal> is not specified, + <command>INSERT</command> and <command>UPDATE</command> commands on the view are allowed to create rows that are not visible through the view. The following check options are supported: @@ -191,7 +191,7 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <para> 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 <literal>CHECK OPTION</>). + not checked (unless they also specify the <literal>CHECK OPTION</literal>). </para> </listitem> </varlistentry> @@ -201,9 +201,9 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <listitem> <para> New rows are checked against the conditions of the view and all - underlying base views. If the <literal>CHECK OPTION</> is specified, - and neither <literal>LOCAL</> nor <literal>CASCADED</> is specified, - then <literal>CASCADED</> is assumed. + underlying base views. If the <literal>CHECK OPTION</literal> is specified, + and neither <literal>LOCAL</literal> nor <literal>CASCADED</literal> is specified, + then <literal>CASCADED</literal> is assumed. </para> </listitem> </varlistentry> @@ -211,26 +211,26 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR </para> <para> - The <literal>CHECK OPTION</> may not be used with <literal>RECURSIVE</> + The <literal>CHECK OPTION</literal> may not be used with <literal>RECURSIVE</literal> views. </para> <para> - Note that the <literal>CHECK OPTION</> is only supported on views that - are automatically updatable, and do not have <literal>INSTEAD OF</> - triggers or <literal>INSTEAD</> rules. If an automatically updatable - view is defined on top of a base view that has <literal>INSTEAD OF</> - triggers, then the <literal>LOCAL CHECK OPTION</> may be used to check + Note that the <literal>CHECK OPTION</literal> is only supported on views that + are automatically updatable, and do not have <literal>INSTEAD OF</literal> + triggers or <literal>INSTEAD</literal> rules. If an automatically updatable + view is defined on top of a base view that has <literal>INSTEAD OF</literal> + triggers, then the <literal>LOCAL CHECK OPTION</literal> may be used to check the conditions on the automatically updatable view, but the conditions - on the base view with <literal>INSTEAD OF</> triggers will not be + on the base view with <literal>INSTEAD OF</literal> 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 <literal>INSTEAD</> rule that causes the - <command>INSERT</> or <command>UPDATE</> command to be rewritten, then + relations has an <literal>INSTEAD</literal> rule that causes the + <command>INSERT</command> or <command>UPDATE</command> 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 <literal>INSTEAD</> rule. + with the <literal>INSTEAD</literal> rule. </para> </listitem> </varlistentry> @@ -251,8 +251,8 @@ CREATE VIEW [ <replaceable>schema</> . ] <replaceable>view_name</> AS WITH RECUR <programlisting> CREATE VIEW vista AS SELECT 'Hello World'; </programlisting> - is bad form because the column name defaults to <literal>?column?</>; - also, the column data type defaults to <type>text</>, which might not + is bad form because the column name defaults to <literal>?column?</literal>; + also, the column data type defaults to <type>text</type>, which might not be what you wanted. Better style for a string literal in a view's result is something like: <programlisting> @@ -271,7 +271,7 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; </para> <para> - When <command>CREATE OR REPLACE VIEW</> is used on an + When <command>CREATE OR REPLACE VIEW</command> is used on an existing view, only the view's defining SELECT rule is changed. Other view properties, including ownership, permissions, and non-SELECT rules, remain unchanged. You must own the view @@ -287,30 +287,30 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; <para> Simple views are automatically updatable: the system will allow - <command>INSERT</>, <command>UPDATE</> and <command>DELETE</> statements + <command>INSERT</command>, <command>UPDATE</command> and <command>DELETE</command> 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: <itemizedlist> <listitem> <para> - The view must have exactly one entry in its <literal>FROM</> list, + The view must have exactly one entry in its <literal>FROM</literal> list, which must be a table or another updatable view. </para> </listitem> <listitem> <para> - The view definition must not contain <literal>WITH</>, - <literal>DISTINCT</>, <literal>GROUP BY</>, <literal>HAVING</>, - <literal>LIMIT</>, or <literal>OFFSET</> clauses at the top level. + The view definition must not contain <literal>WITH</literal>, + <literal>DISTINCT</literal>, <literal>GROUP BY</literal>, <literal>HAVING</literal>, + <literal>LIMIT</literal>, or <literal>OFFSET</literal> clauses at the top level. </para> </listitem> <listitem> <para> - The view definition must not contain set operations (<literal>UNION</>, - <literal>INTERSECT</> or <literal>EXCEPT</>) at the top level. + The view definition must not contain set operations (<literal>UNION</literal>, + <literal>INTERSECT</literal> or <literal>EXCEPT</literal>) at the top level. </para> </listitem> @@ -327,42 +327,42 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; 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 <command>INSERT</> - or <command>UPDATE</> statement attempts to assign a value to it. + column is read-only, and an error will be raised if an <command>INSERT</command> + or <command>UPDATE</command> statement attempts to assign a value to it. </para> <para> If the view is automatically updatable the system will convert any - <command>INSERT</>, <command>UPDATE</> or <command>DELETE</> statement + <command>INSERT</command>, <command>UPDATE</command> or <command>DELETE</command> statement on the view into the corresponding statement on the underlying base - relation. <command>INSERT</> statements that have an <literal>ON - CONFLICT UPDATE</> clause are fully supported. + relation. <command>INSERT</command> statements that have an <literal>ON + CONFLICT UPDATE</literal> clause are fully supported. </para> <para> - If an automatically updatable view contains a <literal>WHERE</> + If an automatically updatable view contains a <literal>WHERE</literal> condition, the condition restricts which rows of the base relation are - available to be modified by <command>UPDATE</> and <command>DELETE</> - statements on the view. However, an <command>UPDATE</> is allowed to - change a row so that it no longer satisfies the <literal>WHERE</> + available to be modified by <command>UPDATE</command> and <command>DELETE</command> + statements on the view. However, an <command>UPDATE</command> is allowed to + change a row so that it no longer satisfies the <literal>WHERE</literal> condition, and thus is no longer visible through the view. Similarly, - an <command>INSERT</> command can potentially insert base-relation rows - that do not satisfy the <literal>WHERE</> condition and thus are not - visible through the view (<literal>ON CONFLICT UPDATE</> may + an <command>INSERT</command> command can potentially insert base-relation rows + that do not satisfy the <literal>WHERE</literal> condition and thus are not + visible through the view (<literal>ON CONFLICT UPDATE</literal> may similarly affect an existing row not visible through the view). - The <literal>CHECK OPTION</> may be used to prevent - <command>INSERT</> and <command>UPDATE</> commands from creating + The <literal>CHECK OPTION</literal> may be used to prevent + <command>INSERT</command> and <command>UPDATE</command> commands from creating such rows that are not visible through the view. </para> <para> If an automatically updatable view is marked with the - <literal>security_barrier</> property then all the view's <literal>WHERE</> + <literal>security_barrier</literal> property then all the view's <literal>WHERE</literal> conditions (and any conditions using operators which are marked as <literal>LEAKPROOF</literal>) will always be evaluated before any conditions that a user of the view has added. See <xref linkend="rules-privileges"> for full details. Note that, due to this, rows which are not ultimately returned (because they do not - pass the user's <literal>WHERE</> conditions) may still end up being locked. + pass the user's <literal>WHERE</literal> conditions) may still end up being locked. <command>EXPLAIN</command> can be used to see which conditions are applied at the relation level (and therefore do not lock rows) and which are not. @@ -372,7 +372,7 @@ CREATE VIEW vista AS SELECT text 'Hello World' AS hello; 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 <literal>INSTEAD OF</> triggers on the view, which must + creating <literal>INSTEAD OF</literal> triggers on the view, which must convert attempted inserts, etc. on the view into appropriate actions on other tables. For more information see <xref linkend="sql-createtrigger">. Another possibility is to create rules @@ -404,13 +404,13 @@ CREATE VIEW comedies AS WHERE kind = 'Comedy'; </programlisting> This will create a view containing the columns that are in the - <literal>film</> table at the time of view creation. Though - <literal>*</> was used to create the view, columns added later to + <literal>film</literal> table at the time of view creation. Though + <literal>*</literal> was used to create the view, columns added later to the table will not be part of the view. </para> <para> - Create a view with <literal>LOCAL CHECK OPTION</>: + Create a view with <literal>LOCAL CHECK OPTION</literal>: <programlisting> CREATE VIEW universal_comedies AS @@ -419,16 +419,16 @@ CREATE VIEW universal_comedies AS WHERE classification = 'U' WITH LOCAL CHECK OPTION; </programlisting> - This will create a view based on the <literal>comedies</> view, showing - only films with <literal>kind = 'Comedy'</> and - <literal>classification = 'U'</>. Any attempt to <command>INSERT</> or - <command>UPDATE</> a row in the view will be rejected if the new row - doesn't have <literal>classification = 'U'</>, but the film - <literal>kind</> will not be checked. + This will create a view based on the <literal>comedies</literal> view, showing + only films with <literal>kind = 'Comedy'</literal> and + <literal>classification = 'U'</literal>. Any attempt to <command>INSERT</command> or + <command>UPDATE</command> a row in the view will be rejected if the new row + doesn't have <literal>classification = 'U'</literal>, but the film + <literal>kind</literal> will not be checked. </para> <para> - Create a view with <literal>CASCADED CHECK OPTION</>: + Create a view with <literal>CASCADED CHECK OPTION</literal>: <programlisting> CREATE VIEW pg_comedies AS @@ -437,8 +437,8 @@ CREATE VIEW pg_comedies AS WHERE classification = 'PG' WITH CASCADED CHECK OPTION; </programlisting> - This will create a view that checks both the <literal>kind</> and - <literal>classification</> of new rows. + This will create a view that checks both the <literal>kind</literal> and + <literal>classification</literal> of new rows. </para> <para> @@ -454,10 +454,10 @@ CREATE VIEW comedies AS FROM films f WHERE f.kind = 'Comedy'; </programlisting> - This view will support <command>INSERT</>, <command>UPDATE</> and - <command>DELETE</>. All the columns from the <literal>films</> table will - be updatable, whereas the computed columns <literal>country</> and - <literal>avg_rating</> will be read-only. + This view will support <command>INSERT</command>, <command>UPDATE</command> and + <command>DELETE</command>. All the columns from the <literal>films</literal> table will + be updatable, whereas the computed columns <literal>country</literal> and + <literal>avg_rating</literal> will be read-only. </para> <para> @@ -469,7 +469,7 @@ UNION ALL SELECT n+1 FROM nums_1_100 WHERE n < 100; </programlisting> Notice that although the recursive view's name is schema-qualified in this - <command>CREATE</>, its internal self-reference is not schema-qualified. + <command>CREATE</command>, its internal self-reference is not schema-qualified. This is because the implicitly-created CTE's name cannot be schema-qualified. </para> @@ -482,7 +482,7 @@ UNION ALL <command>CREATE OR REPLACE VIEW</command> is a <productname>PostgreSQL</productname> language extension. So is the concept of a temporary view. - The <literal>WITH ( ... )</> clause is an extension as well. + The <literal>WITH ( ... )</literal> clause is an extension as well. </para> </refsect1> diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 9fc4c16a810..0112d3a848f 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -86,8 +86,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-D <replaceable class="parameter">tablespace</replaceable></></term> - <term><option>--tablespace=<replaceable class="parameter">tablespace</replaceable></></term> + <term><option>-D <replaceable class="parameter">tablespace</replaceable></option></term> + <term><option>--tablespace=<replaceable class="parameter">tablespace</replaceable></option></term> <listitem> <para> Specifies the default tablespace for the database. (This name @@ -97,8 +97,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>createdb</application> generates @@ -108,8 +108,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-E <replaceable class="parameter">encoding</replaceable></></term> - <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></></term> + <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term> + <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term> <listitem> <para> Specifies the character encoding scheme to be used in this @@ -121,8 +121,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-l <replaceable class="parameter">locale</replaceable></></term> - <term><option>--locale=<replaceable class="parameter">locale</replaceable></></term> + <term><option>-l <replaceable class="parameter">locale</replaceable></option></term> + <term><option>--locale=<replaceable class="parameter">locale</replaceable></option></term> <listitem> <para> Specifies the locale to be used in this database. This is equivalent @@ -132,7 +132,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></></term> + <term><option>--lc-collate=<replaceable class="parameter">locale</replaceable></option></term> <listitem> <para> Specifies the LC_COLLATE setting to be used in this database. @@ -141,7 +141,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></></term> + <term><option>--lc-ctype=<replaceable class="parameter">locale</replaceable></option></term> <listitem> <para> Specifies the LC_CTYPE setting to be used in this database. @@ -150,8 +150,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-O <replaceable class="parameter">owner</replaceable></></term> - <term><option>--owner=<replaceable class="parameter">owner</replaceable></></term> + <term><option>-O <replaceable class="parameter">owner</replaceable></option></term> + <term><option>--owner=<replaceable class="parameter">owner</replaceable></option></term> <listitem> <para> Specifies the database user who will own the new database. @@ -161,8 +161,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-T <replaceable class="parameter">template</replaceable></></term> - <term><option>--template=<replaceable class="parameter">template</replaceable></></term> + <term><option>-T <replaceable class="parameter">template</replaceable></option></term> + <term><option>--template=<replaceable class="parameter">template</replaceable></option></term> <listitem> <para> Specifies the template database from which to build this @@ -172,8 +172,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>createdb</application> version and exit. @@ -182,8 +182,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>createdb</application> command line @@ -209,8 +209,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -221,8 +221,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or the local Unix domain socket file @@ -232,8 +232,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -242,8 +242,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -257,8 +257,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>createdb</application> to prompt for a @@ -271,14 +271,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>createdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to when creating the @@ -325,8 +325,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -362,7 +362,7 @@ PostgreSQL documentation <para> To create the database <literal>demo</literal> using the - server on host <literal>eden</>, port 5000, using the + server on host <literal>eden</literal>, port 5000, using the <literal>template0</literal> template database, here is the command-line command and the underlying SQL command: <screen> diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index fda77976ff2..788ee81dafb 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -34,15 +34,15 @@ PostgreSQL documentation <para> <application>createuser</application> creates a new <productname>PostgreSQL</productname> user (or more precisely, a role). - Only superusers and users with <literal>CREATEROLE</> privilege can create + Only superusers and users with <literal>CREATEROLE</literal> privilege can create new users, so <application>createuser</application> must be invoked by someone who can connect as a superuser or a user with - <literal>CREATEROLE</> privilege. + <literal>CREATEROLE</literal> privilege. </para> <para> If you wish to create a new superuser, you must connect as a - superuser, not merely with <literal>CREATEROLE</> privilege. + superuser, not merely with <literal>CREATEROLE</literal> privilege. Being a superuser implies the ability to bypass all access permission checks within the database, so superuserdom should not be granted lightly. </para> @@ -61,7 +61,7 @@ PostgreSQL documentation <title>Options</title> <para> - <application>createuser</> accepts the following command-line arguments: + <application>createuser</application> accepts the following command-line arguments: <variablelist> <varlistentry> @@ -77,8 +77,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-c <replaceable class="parameter">number</replaceable></></term> - <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></></term> + <term><option>-c <replaceable class="parameter">number</replaceable></option></term> + <term><option>--connection-limit=<replaceable class="parameter">number</replaceable></option></term> <listitem> <para> Set a maximum number of connections for the new user. @@ -88,8 +88,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-d</></term> - <term><option>--createdb</></term> + <term><option>-d</option></term> + <term><option>--createdb</option></term> <listitem> <para> The new user will be allowed to create databases. @@ -98,8 +98,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-D</></term> - <term><option>--no-createdb</></term> + <term><option>-D</option></term> + <term><option>--no-createdb</option></term> <listitem> <para> The new user will not be allowed to create databases. This is the @@ -109,8 +109,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>createuser</application> generates @@ -120,8 +120,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-E</></term> - <term><option>--encrypted</></term> + <term><option>-E</option></term> + <term><option>--encrypted</option></term> <listitem> <para> This option is obsolete but still accepted for backward @@ -131,21 +131,21 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-g <replaceable class="parameter">role</replaceable></></term> - <term><option>--role=<replaceable class="parameter">role</replaceable></></term> + <term><option>-g <replaceable class="parameter">role</replaceable></option></term> + <term><option>--role=<replaceable class="parameter">role</replaceable></option></term> <listitem> <para> Indicates role to which this role will be added immediately as a new member. Multiple roles to which this role will be added as a member can be specified by writing multiple - <option>-g</> switches. + <option>-g</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-i</></term> - <term><option>--inherit</></term> + <term><option>-i</option></term> + <term><option>--inherit</option></term> <listitem> <para> The new role will automatically inherit privileges of roles @@ -156,8 +156,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-I</></term> - <term><option>--no-inherit</></term> + <term><option>-I</option></term> + <term><option>--no-inherit</option></term> <listitem> <para> The new role will not automatically inherit privileges of roles @@ -167,7 +167,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--interactive</></term> + <term><option>--interactive</option></term> <listitem> <para> Prompt for the user name if none is specified on the command line, and @@ -181,8 +181,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-l</></term> - <term><option>--login</></term> + <term><option>-l</option></term> + <term><option>--login</option></term> <listitem> <para> The new user will be allowed to log in (that is, the user name @@ -193,8 +193,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-L</></term> - <term><option>--no-login</></term> + <term><option>-L</option></term> + <term><option>--no-login</option></term> <listitem> <para> The new user will not be allowed to log in. @@ -205,8 +205,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-P</></term> - <term><option>--pwprompt</></term> + <term><option>-P</option></term> + <term><option>--pwprompt</option></term> <listitem> <para> If given, <application>createuser</application> will issue a prompt for @@ -217,19 +217,19 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-r</></term> - <term><option>--createrole</></term> + <term><option>-r</option></term> + <term><option>--createrole</option></term> <listitem> <para> The new user will be allowed to create new roles (that is, - this user will have <literal>CREATEROLE</> privilege). + this user will have <literal>CREATEROLE</literal> privilege). </para> </listitem> </varlistentry> <varlistentry> - <term><option>-R</></term> - <term><option>--no-createrole</></term> + <term><option>-R</option></term> + <term><option>--no-createrole</option></term> <listitem> <para> The new user will not be allowed to create new roles. This is the @@ -239,8 +239,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-s</></term> - <term><option>--superuser</></term> + <term><option>-s</option></term> + <term><option>--superuser</option></term> <listitem> <para> The new user will be a superuser. @@ -249,8 +249,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-S</></term> - <term><option>--no-superuser</></term> + <term><option>-S</option></term> + <term><option>--no-superuser</option></term> <listitem> <para> The new user will not be a superuser. This is the default. @@ -259,8 +259,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>createuser</application> version and exit. @@ -269,7 +269,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--replication</></term> + <term><option>--replication</option></term> <listitem> <para> The new user will have the <literal>REPLICATION</literal> privilege, @@ -280,7 +280,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--no-replication</></term> + <term><option>--no-replication</option></term> <listitem> <para> The new user will not have the <literal>REPLICATION</literal> @@ -291,8 +291,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>createuser</application> command line @@ -310,8 +310,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -323,8 +323,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -335,8 +335,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as (not the user name to create). @@ -345,8 +345,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -360,8 +360,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>createuser</application> to prompt for a @@ -375,7 +375,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>createuser</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -403,8 +403,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -451,7 +451,7 @@ PostgreSQL documentation <para> To create the same user <literal>joe</literal> using the - server on host <literal>eden</>, port 5000, with attributes explicitly specified, + server on host <literal>eden</literal>, port 5000, with attributes explicitly specified, taking a look at the underlying command: <screen> <prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput> diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml index 5cb85cc568f..8eae0354af8 100644 --- a/doc/src/sgml/ref/declare.sgml +++ b/doc/src/sgml/ref/declare.sgml @@ -45,7 +45,7 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <note> <para> This page describes usage of cursors at the SQL command level. - If you are trying to use cursors inside a <application>PL/pgSQL</> + If you are trying to use cursors inside a <application>PL/pgSQL</application> function, the rules are different — see <xref linkend="plpgsql-cursors">. </para> @@ -144,13 +144,13 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <para> Normal cursors return data in text format, the same as a - <command>SELECT</> would produce. The <literal>BINARY</> option + <command>SELECT</command> would produce. The <literal>BINARY</literal> 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 <literal>1</> with a default cursor, + you would get a string of <literal>1</literal> 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). @@ -165,8 +165,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <note> <para> - When the client application uses the <quote>extended query</> protocol - to issue a <command>FETCH</> command, the Bind protocol message + When the client application uses the <quote>extended query</quote> protocol + to issue a <command>FETCH</command> 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 @@ -177,7 +177,7 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <para> Unless <literal>WITH HOLD</literal> is specified, the cursor created by this command can only be used within the current - transaction. Thus, <command>DECLARE</> without <literal>WITH + transaction. Thus, <command>DECLARE</command> without <literal>WITH HOLD</literal> is useless outside a transaction block: the cursor would survive only to the completion of the statement. Therefore <productname>PostgreSQL</productname> reports an error if such a @@ -204,25 +204,25 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI <para> <literal>WITH HOLD</literal> may not be specified when the query - includes <literal>FOR UPDATE</> or <literal>FOR SHARE</>. + includes <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>. </para> <para> - The <literal>SCROLL</> option should be specified when defining a + The <literal>SCROLL</literal> 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, <productname>PostgreSQL</productname> will allow - backward fetches without <literal>SCROLL</>, if the cursor's query + backward fetches without <literal>SCROLL</literal>, if the cursor's 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 <literal>SCROLL</literal>. If <literal>NO SCROLL</> is + with <literal>SCROLL</literal>. If <literal>NO SCROLL</literal> is specified, then backward fetches are disallowed in any case. </para> <para> Backward fetches are also disallowed when the query - includes <literal>FOR UPDATE</> or <literal>FOR SHARE</>; therefore + includes <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal>; therefore <literal>SCROLL</literal> may not be specified in this case. </para> @@ -241,42 +241,42 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI </caution> <para> - If the cursor's query includes <literal>FOR UPDATE</> or <literal>FOR - SHARE</>, then returned rows are locked at the time they are first + If the cursor's query includes <literal>FOR UPDATE</literal> or <literal>FOR + SHARE</literal>, then returned rows are locked at the time they are first fetched, in the same way as for a regular <xref linkend="sql-select"> command with these options. In addition, the returned rows will be the most up-to-date versions; therefore these options provide the equivalent of what the SQL standard - calls a <quote>sensitive cursor</>. (Specifying <literal>INSENSITIVE</> - together with <literal>FOR UPDATE</> or <literal>FOR SHARE</> is an error.) + calls a <quote>sensitive cursor</quote>. (Specifying <literal>INSENSITIVE</literal> + together with <literal>FOR UPDATE</literal> or <literal>FOR SHARE</literal> is an error.) </para> <caution> <para> - It is generally recommended to use <literal>FOR UPDATE</> if the cursor - is intended to be used with <command>UPDATE ... WHERE CURRENT OF</> or - <command>DELETE ... WHERE CURRENT OF</>. Using <literal>FOR UPDATE</> + It is generally recommended to use <literal>FOR UPDATE</literal> if the cursor + is intended to be used with <command>UPDATE ... WHERE CURRENT OF</command> or + <command>DELETE ... WHERE CURRENT OF</command>. Using <literal>FOR UPDATE</literal> prevents other sessions from changing the rows between the time they are - fetched and the time they are updated. Without <literal>FOR UPDATE</>, - a subsequent <literal>WHERE CURRENT OF</> command will have no effect if + fetched and the time they are updated. Without <literal>FOR UPDATE</literal>, + a subsequent <literal>WHERE CURRENT OF</literal> command will have no effect if the row was changed since the cursor was created. </para> <para> - Another reason to use <literal>FOR UPDATE</> is that without it, a - subsequent <literal>WHERE CURRENT OF</> might fail if the cursor query + Another reason to use <literal>FOR UPDATE</literal> is that without it, a + subsequent <literal>WHERE CURRENT OF</literal> might fail if the cursor query does not meet the SQL standard's rules for being <quote>simply - updatable</> (in particular, the cursor must reference just one table - and not use grouping or <literal>ORDER BY</>). Cursors + updatable</quote> (in particular, the cursor must reference just one table + and not use grouping or <literal>ORDER BY</literal>). 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. </para> <para> - The main reason not to use <literal>FOR UPDATE</> with <literal>WHERE - CURRENT OF</> is if you need the cursor to be scrollable, or to be + The main reason not to use <literal>FOR UPDATE</literal> with <literal>WHERE + CURRENT OF</literal> is if you need the cursor to be scrollable, or to be insensitive to the subsequent updates (that is, continue to show the old data). If this is a requirement, pay close heed to the caveats shown above. @@ -321,13 +321,13 @@ DECLARE liahona CURSOR FOR SELECT * FROM films; The SQL standard says that it is implementation-dependent whether cursors are sensitive to concurrent updates of the underlying data by default. In <productname>PostgreSQL</productname>, cursors are insensitive by default, - and can be made sensitive by specifying <literal>FOR UPDATE</>. Other + and can be made sensitive by specifying <literal>FOR UPDATE</literal>. Other products may work differently. </para> <para> The SQL standard allows cursors only in embedded - <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</> + <acronym>SQL</acronym> and in modules. <productname>PostgreSQL</productname> permits cursors to be used interactively. </para> diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml index 8ced7de7be6..570e9aa7108 100644 --- a/doc/src/sgml/ref/delete.sgml +++ b/doc/src/sgml/ref/delete.sgml @@ -55,12 +55,12 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * </para> <para> - The optional <literal>RETURNING</> clause causes <command>DELETE</> + The optional <literal>RETURNING</literal> clause causes <command>DELETE</command> to compute and return value(s) based on each row actually deleted. Any expression using the table's columns, and/or columns of other tables mentioned in <literal>USING</literal>, can be computed. - The syntax of the <literal>RETURNING</> list is identical to that of the - output list of <command>SELECT</>. + The syntax of the <literal>RETURNING</literal> list is identical to that of the + output list of <command>SELECT</command>. </para> <para> @@ -81,7 +81,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> The <literal>WITH</literal> clause allows you to specify one or more - subqueries that can be referenced by name in the <command>DELETE</> + subqueries that can be referenced by name in the <command>DELETE</command> query. See <xref linkend="queries-with"> and <xref linkend="sql-select"> for details. </para> @@ -93,11 +93,11 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> The name (optionally schema-qualified) of the table to delete rows - from. If <literal>ONLY</> is specified before the table name, + from. If <literal>ONLY</literal> is specified before the table name, matching rows are deleted from the named table only. If - <literal>ONLY</> is not specified, matching rows are also deleted + <literal>ONLY</literal> is not specified, matching rows are also deleted from any tables inheriting from the named table. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -109,9 +109,9 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <para> A substitute name for the target table. When an alias is provided, it completely hides the actual name of the table. For - example, given <literal>DELETE FROM foo AS f</>, the remainder + example, given <literal>DELETE FROM foo AS f</literal>, the remainder of the <command>DELETE</command> statement must refer to this - table as <literal>f</> not <literal>foo</>. + table as <literal>f</literal> not <literal>foo</literal>. </para> </listitem> </varlistentry> @@ -121,7 +121,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> A list of table expressions, allowing columns from other tables - to appear in the <literal>WHERE</> condition. This is similar + to appear in the <literal>WHERE</literal> condition. This is similar to the list of tables that can be specified in the <xref linkend="sql-from" endterm="sql-from-title"> of a <command>SELECT</command> statement; for example, an alias for @@ -137,7 +137,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <listitem> <para> An expression that returns a value of type <type>boolean</type>. - Only rows for which this expression returns <literal>true</> + Only rows for which this expression returns <literal>true</literal> will be deleted. </para> </listitem> @@ -147,15 +147,15 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <term><replaceable class="parameter">cursor_name</replaceable></term> <listitem> <para> - The name of the cursor to use in a <literal>WHERE CURRENT OF</> + The name of the cursor to use in a <literal>WHERE CURRENT OF</literal> 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 <command>DELETE</>'s target table. - Note that <literal>WHERE CURRENT OF</> cannot be + query on the <command>DELETE</command>'s target table. + Note that <literal>WHERE CURRENT OF</literal> cannot be specified together with a Boolean condition. See <xref linkend="sql-declare"> for more information about using cursors with - <literal>WHERE CURRENT OF</>. + <literal>WHERE CURRENT OF</literal>. </para> </listitem> </varlistentry> @@ -164,11 +164,11 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <term><replaceable class="parameter">output_expression</replaceable></term> <listitem> <para> - An expression to be computed and returned by the <command>DELETE</> + An expression to be computed and returned by the <command>DELETE</command> command after each row is deleted. The expression can use any column names of the table named by <replaceable class="parameter">table_name</replaceable> - or table(s) listed in <literal>USING</>. - Write <literal>*</> to return all columns. + or table(s) listed in <literal>USING</literal>. + Write <literal>*</literal> to return all columns. </para> </listitem> </varlistentry> @@ -188,7 +188,7 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * <title>Outputs</title> <para> - On successful completion, a <command>DELETE</> command returns a command + On successful completion, a <command>DELETE</command> command returns a command tag of the form <screen> DELETE <replaceable class="parameter">count</replaceable> @@ -197,16 +197,16 @@ DELETE <replaceable class="parameter">count</replaceable> of rows deleted. Note that the number may be less than the number of rows that matched the <replaceable class="parameter">condition</replaceable> when deletes were - suppressed by a <literal>BEFORE DELETE</> trigger. If <replaceable + suppressed by a <literal>BEFORE DELETE</literal> trigger. If <replaceable class="parameter">count</replaceable> is 0, no rows were deleted by the query (this is not considered an error). </para> <para> - If the <command>DELETE</> command contains a <literal>RETURNING</> - clause, the result will be similar to that of a <command>SELECT</> + If the <command>DELETE</command> command contains a <literal>RETURNING</literal> + clause, the result will be similar to that of a <command>SELECT</command> statement containing the columns and values defined in the - <literal>RETURNING</> list, computed over the row(s) deleted by the + <literal>RETURNING</literal> list, computed over the row(s) deleted by the command. </para> </refsect1> @@ -216,16 +216,16 @@ DELETE <replaceable class="parameter">count</replaceable> <para> <productname>PostgreSQL</productname> lets you reference columns of - other tables in the <literal>WHERE</> condition by specifying the + other tables in the <literal>WHERE</literal> condition by specifying the other tables in the <literal>USING</literal> clause. For example, to delete all films produced by a given producer, one can do: <programlisting> DELETE FROM films USING producers WHERE producer_id = producers.id AND producers.name = 'foo'; </programlisting> - What is essentially happening here is a join between <structname>films</> - and <structname>producers</>, with all successfully joined - <structname>films</> rows being marked for deletion. + What is essentially happening here is a join between <structname>films</structname> + and <structname>producers</structname>, with all successfully joined + <structname>films</structname> rows being marked for deletion. This syntax is not standard. A more standard way to do it is: <programlisting> DELETE FROM films @@ -261,8 +261,8 @@ DELETE FROM tasks WHERE status = 'DONE' RETURNING *; </para> <para> - Delete the row of <structname>tasks</> on which the cursor - <literal>c_tasks</> is currently positioned: + Delete the row of <structname>tasks</structname> on which the cursor + <literal>c_tasks</literal> is currently positioned: <programlisting> DELETE FROM tasks WHERE CURRENT OF c_tasks; </programlisting></para> @@ -273,9 +273,9 @@ DELETE FROM tasks WHERE CURRENT OF c_tasks; <para> This command conforms to the <acronym>SQL</acronym> standard, except - that the <literal>USING</literal> and <literal>RETURNING</> clauses + that the <literal>USING</literal> and <literal>RETURNING</literal> clauses are <productname>PostgreSQL</productname> extensions, as is the ability - to use <literal>WITH</> with <command>DELETE</>. + to use <literal>WITH</literal> with <command>DELETE</command>. </para> </refsect1> diff --git a/doc/src/sgml/ref/discard.sgml b/doc/src/sgml/ref/discard.sgml index e859bf7bab7..f432e70430d 100644 --- a/doc/src/sgml/ref/discard.sgml +++ b/doc/src/sgml/ref/discard.sgml @@ -29,10 +29,10 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP } <title>Description</title> <para> - <command>DISCARD</> releases internal resources associated with a + <command>DISCARD</command> releases internal resources associated with a database session. This command is useful for partially or fully resetting the session's state. There are several subcommands to - release different types of resources; the <command>DISCARD ALL</> + release different types of resources; the <command>DISCARD ALL</command> variant subsumes all the others, and also resets additional state. </para> </refsect1> @@ -57,9 +57,9 @@ DISCARD { ALL | PLANS | SEQUENCES | TEMPORARY | TEMP } <listitem> <para> Discards all cached sequence-related state, - including <function>currval()</>/<function>lastval()</> + including <function>currval()</function>/<function>lastval()</function> information and any preallocated sequence values that have not - yet been returned by <function>nextval()</>. + yet been returned by <function>nextval()</function>. (See <xref linkend="sql-createsequence"> for a description of preallocated sequence values.) </para> @@ -104,7 +104,7 @@ DISCARD TEMP; <title>Notes</title> <para> - <command>DISCARD ALL</> cannot be executed inside a transaction block. + <command>DISCARD ALL</command> cannot be executed inside a transaction block. </para> </refsect1> diff --git a/doc/src/sgml/ref/do.sgml b/doc/src/sgml/ref/do.sgml index d4da32c34dc..5d2e9b1b8ce 100644 --- a/doc/src/sgml/ref/do.sgml +++ b/doc/src/sgml/ref/do.sgml @@ -39,12 +39,12 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <para> The code block is treated as though it were the body of a function - with no parameters, returning <type>void</>. It is parsed and + with no parameters, returning <type>void</type>. It is parsed and executed a single time. </para> <para> - The optional <literal>LANGUAGE</> clause can be written either + The optional <literal>LANGUAGE</literal> clause can be written either before or after the code block. </para> </refsect1> @@ -58,7 +58,7 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <listitem> <para> The procedural language code to be executed. This must be specified - as a string literal, just as in <command>CREATE FUNCTION</>. + as a string literal, just as in <command>CREATE FUNCTION</command>. Use of a dollar-quoted literal is recommended. </para> </listitem> @@ -69,7 +69,7 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <listitem> <para> The name of the procedural language the code is written in. - If omitted, the default is <literal>plpgsql</>. + If omitted, the default is <literal>plpgsql</literal>. </para> </listitem> </varlistentry> @@ -81,12 +81,12 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <para> The procedural language to be used must already have been installed - into the current database by means of <command>CREATE LANGUAGE</>. - <literal>plpgsql</> is installed by default, but other languages are not. + into the current database by means of <command>CREATE LANGUAGE</command>. + <literal>plpgsql</literal> is installed by default, but other languages are not. </para> <para> - The user must have <literal>USAGE</> privilege for the procedural + The user must have <literal>USAGE</literal> 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. @@ -96,8 +96,8 @@ DO [ LANGUAGE <replaceable class="parameter">lang_name</replaceable> ] <replacea <refsect1 id="sql-do-examples"> <title id="sql-do-examples-title">Examples</title> <para> - Grant all privileges on all views in schema <literal>public</> to - role <literal>webuser</>: + Grant all privileges on all views in schema <literal>public</literal> to + role <literal>webuser</literal>: <programlisting> DO $$DECLARE r record; BEGIN diff --git a/doc/src/sgml/ref/drop_access_method.sgml b/doc/src/sgml/ref/drop_access_method.sgml index 8aa9197fe4a..aa5d2505c7d 100644 --- a/doc/src/sgml/ref/drop_access_method.sgml +++ b/doc/src/sgml/ref/drop_access_method.sgml @@ -85,7 +85,7 @@ DROP ACCESS METHOD [ IF EXISTS ] <replaceable class="parameter">name</replaceabl <title>Examples</title> <para> - Drop the access method <literal>heptree</>: + Drop the access method <literal>heptree</literal>: <programlisting> DROP ACCESS METHOD heptree; </programlisting></para> @@ -96,7 +96,7 @@ DROP ACCESS METHOD heptree; <para> <command>DROP ACCESS METHOD</command> is a - <productname>PostgreSQL</> extension. + <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_aggregate.sgml b/doc/src/sgml/ref/drop_aggregate.sgml index dde1ea24449..ac29e7a4193 100644 --- a/doc/src/sgml/ref/drop_aggregate.sgml +++ b/doc/src/sgml/ref/drop_aggregate.sgml @@ -70,8 +70,8 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr <listitem> <para> - The mode of an argument: <literal>IN</> or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal> or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. </para> </listitem> </varlistentry> @@ -94,10 +94,10 @@ DROP AGGREGATE [ IF EXISTS ] <replaceable>name</replaceable> ( <replaceable>aggr <listitem> <para> An input data type on which the aggregate function operates. - To reference a zero-argument aggregate function, write <literal>*</> + To reference a zero-argument aggregate function, write <literal>*</literal> in place of the list of argument specifications. To reference an ordered-set aggregate function, write - <literal>ORDER BY</> between the direct and aggregated argument + <literal>ORDER BY</literal> between the direct and aggregated argument specifications. </para> </listitem> @@ -148,7 +148,7 @@ DROP AGGREGATE myavg(integer); </para> <para> - To remove the hypothetical-set aggregate function <literal>myrank</>, + To remove the hypothetical-set aggregate function <literal>myrank</literal>, which takes an arbitrary list of ordering columns and a matching list of direct arguments: <programlisting> diff --git a/doc/src/sgml/ref/drop_collation.sgml b/doc/src/sgml/ref/drop_collation.sgml index 2177d8e5d65..23f8e88fc95 100644 --- a/doc/src/sgml/ref/drop_collation.sgml +++ b/doc/src/sgml/ref/drop_collation.sgml @@ -83,7 +83,7 @@ DROP COLLATION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRIC <title>Examples</title> <para> - To drop the collation named <literal>german</>: + To drop the collation named <literal>german</literal>: <programlisting> DROP COLLATION german; </programlisting></para> @@ -95,7 +95,7 @@ DROP COLLATION german; <para> The <command>DROP COLLATION</command> command conforms to the <acronym>SQL</acronym> standard, apart from the <literal>IF - EXISTS</> option, which is a <productname>PostgreSQL</> extension. + EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_conversion.sgml b/doc/src/sgml/ref/drop_conversion.sgml index 1a33b3dcc52..9d56ec51a59 100644 --- a/doc/src/sgml/ref/drop_conversion.sgml +++ b/doc/src/sgml/ref/drop_conversion.sgml @@ -74,7 +74,7 @@ DROP CONVERSION [ IF EXISTS ] <replaceable>name</replaceable> [ CASCADE | RESTRI <title>Examples</title> <para> - To drop the conversion named <literal>myname</>: + To drop the conversion named <literal>myname</literal>: <programlisting> DROP CONVERSION myname; </programlisting></para> diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml index 44436ad48db..7e5fbe7396c 100644 --- a/doc/src/sgml/ref/drop_database.sgml +++ b/doc/src/sgml/ref/drop_database.sgml @@ -71,7 +71,7 @@ DROP DATABASE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <command>DROP DATABASE</> cannot be executed inside a transaction + <command>DROP DATABASE</command> cannot be executed inside a transaction block. </para> diff --git a/doc/src/sgml/ref/drop_domain.sgml b/doc/src/sgml/ref/drop_domain.sgml index ba546165c20..b1dac01e652 100644 --- a/doc/src/sgml/ref/drop_domain.sgml +++ b/doc/src/sgml/ref/drop_domain.sgml @@ -58,7 +58,7 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, . </varlistentry> <varlistentry> - <term><literal>CASCADE</></term> + <term><literal>CASCADE</literal></term> <listitem> <para> Automatically drop objects that depend on the domain (such as @@ -70,7 +70,7 @@ DROP DOMAIN [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, . </varlistentry> <varlistentry> - <term><literal>RESTRICT</></term> + <term><literal>RESTRICT</literal></term> <listitem> <para> Refuse to drop the domain if any objects depend on it. This is @@ -97,7 +97,7 @@ DROP DOMAIN box; <para> This command conforms to the SQL standard, except for the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_extension.sgml b/doc/src/sgml/ref/drop_extension.sgml index ba529220135..f75308a20d3 100644 --- a/doc/src/sgml/ref/drop_extension.sgml +++ b/doc/src/sgml/ref/drop_extension.sgml @@ -79,7 +79,7 @@ DROP EXTENSION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ <para> Refuse to drop the extension if any objects depend on it (other than its own member objects and other extensions listed in the same - <command>DROP</> command). This is the default. + <command>DROP</command> command). This is the default. </para> </listitem> </varlistentry> @@ -97,7 +97,7 @@ DROP EXTENSION hstore; </programlisting> This command will fail if any of <literal>hstore</literal>'s objects are in use in the database, for example if any tables have columns - of the <type>hstore</> type. Add the <literal>CASCADE</> option to + of the <type>hstore</type> type. Add the <literal>CASCADE</literal> option to forcibly remove those dependent objects as well. </para> </refsect1> @@ -106,7 +106,7 @@ DROP EXTENSION hstore; <title>Compatibility</title> <para> - <command>DROP EXTENSION</command> is a <productname>PostgreSQL</> + <command>DROP EXTENSION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml index 702cc021dbc..a3c73a0d46b 100644 --- a/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml +++ b/doc/src/sgml/ref/drop_foreign_data_wrapper.sgml @@ -86,7 +86,7 @@ DROP FOREIGN DATA WRAPPER [ IF EXISTS ] <replaceable class="parameter">name</rep <title>Examples</title> <para> - Drop the foreign-data wrapper <literal>dbi</>: + Drop the foreign-data wrapper <literal>dbi</literal>: <programlisting> DROP FOREIGN DATA WRAPPER dbi; </programlisting></para> @@ -97,8 +97,8 @@ DROP FOREIGN DATA WRAPPER dbi; <para> <command>DROP FOREIGN DATA WRAPPER</command> conforms to ISO/IEC - 9075-9 (SQL/MED). The <literal>IF EXISTS</> clause is - a <productname>PostgreSQL</> extension. + 9075-9 (SQL/MED). The <literal>IF EXISTS</literal> clause is + a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_foreign_table.sgml b/doc/src/sgml/ref/drop_foreign_table.sgml index 173eadadd36..456d55d1122 100644 --- a/doc/src/sgml/ref/drop_foreign_table.sgml +++ b/doc/src/sgml/ref/drop_foreign_table.sgml @@ -95,7 +95,7 @@ DROP FOREIGN TABLE films, distributors; <para> This command conforms to the ISO/IEC 9075-9 (SQL/MED), except that the standard only allows one foreign table to be dropped per command, and apart - from the <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + from the <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_function.sgml b/doc/src/sgml/ref/drop_function.sgml index 0aa984528d3..9c9adb9a46d 100644 --- a/doc/src/sgml/ref/drop_function.sgml +++ b/doc/src/sgml/ref/drop_function.sgml @@ -67,14 +67,14 @@ DROP FUNCTION [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [ <listitem> <para> - The mode of an argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + The mode of an argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>DROP FUNCTION</command> does not actually pay - any attention to <literal>OUT</> arguments, since only the input + any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/drop_index.sgml b/doc/src/sgml/ref/drop_index.sgml index 4c838fffffb..de36c135d16 100644 --- a/doc/src/sgml/ref/drop_index.sgml +++ b/doc/src/sgml/ref/drop_index.sgml @@ -44,19 +44,19 @@ DROP INDEX [ CONCURRENTLY ] [ IF EXISTS ] <replaceable class="parameter">name</r <listitem> <para> Drop the index without locking out concurrent selects, inserts, updates, - and deletes on the index's table. A normal <command>DROP INDEX</> + and deletes on the index's table. A normal <command>DROP INDEX</command> acquires 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. </para> <para> There are several caveats to be aware of when using this option. - Only one index name can be specified, and the <literal>CASCADE</> option - is not supported. (Thus, an index that supports a <literal>UNIQUE</> or - <literal>PRIMARY KEY</> constraint cannot be dropped this way.) - Also, regular <command>DROP INDEX</> commands can be + Only one index name can be specified, and the <literal>CASCADE</literal> option + is not supported. (Thus, an index that supports a <literal>UNIQUE</literal> or + <literal>PRIMARY KEY</literal> constraint cannot be dropped this way.) + Also, regular <command>DROP INDEX</command> commands can be performed within a transaction block, but - <command>DROP INDEX CONCURRENTLY</> cannot. + <command>DROP INDEX CONCURRENTLY</command> cannot. </para> </listitem> </varlistentry> diff --git a/doc/src/sgml/ref/drop_language.sgml b/doc/src/sgml/ref/drop_language.sgml index 081bd5fe3ec..524d7583703 100644 --- a/doc/src/sgml/ref/drop_language.sgml +++ b/doc/src/sgml/ref/drop_language.sgml @@ -31,13 +31,13 @@ DROP [ PROCEDURAL ] LANGUAGE [ IF EXISTS ] <replaceable class="parameter">name</ <para> <command>DROP LANGUAGE</command> removes the definition of a previously registered procedural language. You must be a superuser - or the owner of the language to use <command>DROP LANGUAGE</>. + or the owner of the language to use <command>DROP LANGUAGE</command>. </para> <note> <para> As of <productname>PostgreSQL</productname> 9.1, most procedural - languages have been made into <quote>extensions</>, and should + languages have been made into <quote>extensions</quote>, and should therefore be removed with <xref linkend="sql-dropextension"> not <command>DROP LANGUAGE</command>. </para> diff --git a/doc/src/sgml/ref/drop_opclass.sgml b/doc/src/sgml/ref/drop_opclass.sgml index 423a211bcab..83af6d7e485 100644 --- a/doc/src/sgml/ref/drop_opclass.sgml +++ b/doc/src/sgml/ref/drop_opclass.sgml @@ -37,7 +37,7 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="parameter">name</replaceab <command>DROP OPERATOR CLASS</command> 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 - <literal>CASCADE</> for the drop to complete. + <literal>CASCADE</literal> for the drop to complete. </para> </refsect1> @@ -101,13 +101,13 @@ DROP OPERATOR CLASS [ IF EXISTS ] <replaceable class="parameter">name</replaceab <title>Notes</title> <para> - <command>DROP OPERATOR CLASS</> will not drop the operator family + <command>DROP OPERATOR CLASS</command> 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 <command>CREATE OPERATOR CLASS</>). An empty operator + created by <command>CREATE OPERATOR CLASS</command>). An empty operator family is harmless, but for the sake of tidiness you might wish to - remove the family with <command>DROP OPERATOR FAMILY</>; or perhaps - better, use <command>DROP OPERATOR FAMILY</> in the first place. + remove the family with <command>DROP OPERATOR FAMILY</command>; or perhaps + better, use <command>DROP OPERATOR FAMILY</command> in the first place. </para> </refsect1> @@ -122,7 +122,7 @@ DROP OPERATOR CLASS widget_ops USING btree; </programlisting> This command will not succeed if there are any existing indexes - that use the operator class. Add <literal>CASCADE</> to drop + that use the operator class. Add <literal>CASCADE</literal> to drop such indexes along with the operator class. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_opfamily.sgml b/doc/src/sgml/ref/drop_opfamily.sgml index a7b90f306c7..b825978aee9 100644 --- a/doc/src/sgml/ref/drop_opfamily.sgml +++ b/doc/src/sgml/ref/drop_opfamily.sgml @@ -38,7 +38,7 @@ DROP OPERATOR FAMILY [ IF EXISTS ] <replaceable class="parameter">name</replacea 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 - <literal>CASCADE</> for the drop to complete. + <literal>CASCADE</literal> for the drop to complete. </para> </refsect1> @@ -109,7 +109,7 @@ DROP OPERATOR FAMILY float_ops USING btree; </programlisting> This command will not succeed if there are any existing indexes - that use operator classes within the family. Add <literal>CASCADE</> to + that use operator classes within the family. Add <literal>CASCADE</literal> to drop such indexes along with the operator family. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_owned.sgml b/doc/src/sgml/ref/drop_owned.sgml index 0426373d2de..8b4b3644e66 100644 --- a/doc/src/sgml/ref/drop_owned.sgml +++ b/doc/src/sgml/ref/drop_owned.sgml @@ -92,7 +92,7 @@ DROP OWNED BY { <replaceable class="parameter">name</replaceable> | CURRENT_USER <para> The <xref linkend="sql-reassign-owned"> command is an alternative that reassigns the ownership of all the database objects owned by one or - more roles. However, <command>REASSIGN OWNED</> does not deal with + more roles. However, <command>REASSIGN OWNED</command> does not deal with privileges for other objects. </para> diff --git a/doc/src/sgml/ref/drop_publication.sgml b/doc/src/sgml/ref/drop_publication.sgml index bf43db3dac3..1c129c04443 100644 --- a/doc/src/sgml/ref/drop_publication.sgml +++ b/doc/src/sgml/ref/drop_publication.sgml @@ -89,7 +89,7 @@ DROP PUBLICATION mypublication; <title>Compatibility</title> <para> - <command>DROP PUBLICATION</command> is a <productname>PostgreSQL</> + <command>DROP PUBLICATION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_role.sgml b/doc/src/sgml/ref/drop_role.sgml index fcddfeb172c..3c1bbaba6fd 100644 --- a/doc/src/sgml/ref/drop_role.sgml +++ b/doc/src/sgml/ref/drop_role.sgml @@ -31,7 +31,7 @@ DROP ROLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, ... <para> <command>DROP ROLE</command> removes the specified role(s). To drop a superuser role, you must be a superuser yourself; - to drop non-superuser roles, you must have <literal>CREATEROLE</> + to drop non-superuser roles, you must have <literal>CREATEROLE</literal> privilege. </para> @@ -47,7 +47,7 @@ DROP ROLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, ... <para> However, it is not necessary to remove role memberships involving - the role; <command>DROP ROLE</> automatically revokes any memberships + the role; <command>DROP ROLE</command> 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. </para> diff --git a/doc/src/sgml/ref/drop_schema.sgml b/doc/src/sgml/ref/drop_schema.sgml index fd1fcd7e037..bb3af1e1863 100644 --- a/doc/src/sgml/ref/drop_schema.sgml +++ b/doc/src/sgml/ref/drop_schema.sgml @@ -114,7 +114,7 @@ DROP SCHEMA mystuff CASCADE; <command>DROP SCHEMA</command> is fully conforming with the SQL standard, except that the standard only allows one schema to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_sequence.sgml b/doc/src/sgml/ref/drop_sequence.sgml index 9d827f0cb17..5027129b38b 100644 --- a/doc/src/sgml/ref/drop_sequence.sgml +++ b/doc/src/sgml/ref/drop_sequence.sgml @@ -98,7 +98,7 @@ DROP SEQUENCE serial; <command>DROP SEQUENCE</command> conforms to the <acronym>SQL</acronym> standard, except that the standard only allows one sequence to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_server.sgml b/doc/src/sgml/ref/drop_server.sgml index 42acdd41dc1..8ef0e014e4f 100644 --- a/doc/src/sgml/ref/drop_server.sgml +++ b/doc/src/sgml/ref/drop_server.sgml @@ -86,7 +86,7 @@ DROP SERVER [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, . <title>Examples</title> <para> - Drop a server <literal>foo</> if it exists: + Drop a server <literal>foo</literal> if it exists: <programlisting> DROP SERVER IF EXISTS foo; </programlisting></para> @@ -97,8 +97,8 @@ DROP SERVER IF EXISTS foo; <para> <command>DROP SERVER</command> conforms to ISO/IEC 9075-9 - (SQL/MED). The <literal>IF EXISTS</> clause is - a <productname>PostgreSQL</> extension. + (SQL/MED). The <literal>IF EXISTS</literal> clause is + a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_subscription.sgml b/doc/src/sgml/ref/drop_subscription.sgml index f5734e6f300..58b14894757 100644 --- a/doc/src/sgml/ref/drop_subscription.sgml +++ b/doc/src/sgml/ref/drop_subscription.sgml @@ -114,7 +114,7 @@ DROP SUBSCRIPTION mysub; <title>Compatibility</title> <para> - <command>DROP SUBSCRIPTION</command> is a <productname>PostgreSQL</> + <command>DROP SUBSCRIPTION</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_table.sgml b/doc/src/sgml/ref/drop_table.sgml index ae96cf06575..cea7e003511 100644 --- a/doc/src/sgml/ref/drop_table.sgml +++ b/doc/src/sgml/ref/drop_table.sgml @@ -40,8 +40,8 @@ DROP TABLE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> [, .. <command>DROP TABLE</command> 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, <literal>CASCADE</> must be - specified. (<literal>CASCADE</> will remove a dependent view entirely, + constraint of another table, <literal>CASCADE</literal> must be + specified. (<literal>CASCADE</literal> 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.) </para> @@ -112,7 +112,7 @@ DROP TABLE films, distributors; <para> This command conforms to the SQL standard, except that the standard only allows one table to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tablespace.sgml b/doc/src/sgml/ref/drop_tablespace.sgml index ee40cc6b0c3..4343035ebb2 100644 --- a/doc/src/sgml/ref/drop_tablespace.sgml +++ b/doc/src/sgml/ref/drop_tablespace.sgml @@ -39,7 +39,7 @@ DROP TABLESPACE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> in the tablespace even if no objects in the current database are using the tablespace. Also, if the tablespace is listed in the <xref linkend="guc-temp-tablespaces"> setting of any active session, the - <command>DROP</> might fail due to temporary files residing in the + <command>DROP</command> might fail due to temporary files residing in the tablespace. </para> </refsect1> @@ -74,7 +74,7 @@ DROP TABLESPACE [ IF EXISTS ] <replaceable class="parameter">name</replaceable> <title>Notes</title> <para> - <command>DROP TABLESPACE</> cannot be executed inside a transaction block. + <command>DROP TABLESPACE</command> cannot be executed inside a transaction block. </para> </refsect1> @@ -93,7 +93,7 @@ DROP TABLESPACE mystuff; <title>Compatibility</title> <para> - <command>DROP TABLESPACE</command> is a <productname>PostgreSQL</> + <command>DROP TABLESPACE</command> is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tsconfig.sgml b/doc/src/sgml/ref/drop_tsconfig.sgml index e4a1738baeb..cc053beceb7 100644 --- a/doc/src/sgml/ref/drop_tsconfig.sgml +++ b/doc/src/sgml/ref/drop_tsconfig.sgml @@ -94,8 +94,8 @@ DROP TEXT SEARCH CONFIGURATION my_english; </programlisting> This command will not succeed if there are any existing indexes - that reference the configuration in <function>to_tsvector</> calls. - Add <literal>CASCADE</> to + that reference the configuration in <function>to_tsvector</function> calls. + Add <literal>CASCADE</literal> to drop such indexes along with the text search configuration. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tsdictionary.sgml b/doc/src/sgml/ref/drop_tsdictionary.sgml index faa4b3a1e5d..66af10fb0f4 100644 --- a/doc/src/sgml/ref/drop_tsdictionary.sgml +++ b/doc/src/sgml/ref/drop_tsdictionary.sgml @@ -94,7 +94,7 @@ DROP TEXT SEARCH DICTIONARY english; </programlisting> This command will not succeed if there are any existing text search - configurations that use the dictionary. Add <literal>CASCADE</> to + configurations that use the dictionary. Add <literal>CASCADE</literal> to drop such configurations along with the dictionary. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tsparser.sgml b/doc/src/sgml/ref/drop_tsparser.sgml index bc9dae17a5e..3fa9467ebdd 100644 --- a/doc/src/sgml/ref/drop_tsparser.sgml +++ b/doc/src/sgml/ref/drop_tsparser.sgml @@ -92,7 +92,7 @@ DROP TEXT SEARCH PARSER my_parser; </programlisting> This command will not succeed if there are any existing text search - configurations that use the parser. Add <literal>CASCADE</> to + configurations that use the parser. Add <literal>CASCADE</literal> to drop such configurations along with the parser. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_tstemplate.sgml b/doc/src/sgml/ref/drop_tstemplate.sgml index 98f5523e513..ad832754573 100644 --- a/doc/src/sgml/ref/drop_tstemplate.sgml +++ b/doc/src/sgml/ref/drop_tstemplate.sgml @@ -93,7 +93,7 @@ DROP TEXT SEARCH TEMPLATE thesaurus; </programlisting> This command will not succeed if there are any existing text search - dictionaries that use the template. Add <literal>CASCADE</> to + dictionaries that use the template. Add <literal>CASCADE</literal> to drop such dictionaries along with the template. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_type.sgml b/doc/src/sgml/ref/drop_type.sgml index 4ec1b92f329..92ac2729caf 100644 --- a/doc/src/sgml/ref/drop_type.sgml +++ b/doc/src/sgml/ref/drop_type.sgml @@ -96,8 +96,8 @@ DROP TYPE box; <para> This command is similar to the corresponding command in the SQL - standard, apart from the <literal>IF EXISTS</> - option, which is a <productname>PostgreSQL</> extension. + standard, apart from the <literal>IF EXISTS</literal> + option, which is a <productname>PostgreSQL</productname> extension. But note that much of the <command>CREATE TYPE</command> command and the data type extension mechanisms in <productname>PostgreSQL</productname> differ from the SQL standard. diff --git a/doc/src/sgml/ref/drop_user_mapping.sgml b/doc/src/sgml/ref/drop_user_mapping.sgml index eb4c3202939..27284acae4c 100644 --- a/doc/src/sgml/ref/drop_user_mapping.sgml +++ b/doc/src/sgml/ref/drop_user_mapping.sgml @@ -36,7 +36,7 @@ DROP USER MAPPING [ IF EXISTS ] FOR { <replaceable class="parameter">user_name</ <para> 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 <literal>USAGE</> privilege on the server has been + user name if <literal>USAGE</literal> privilege on the server has been granted to the user. </para> </refsect1> @@ -59,9 +59,9 @@ DROP USER MAPPING [ IF EXISTS ] FOR { <replaceable class="parameter">user_name</ <term><replaceable class="parameter">user_name</replaceable></term> <listitem> <para> - User name of the mapping. <literal>CURRENT_USER</> - and <literal>USER</> match the name of the current - user. <literal>PUBLIC</> is used to match all present and + User name of the mapping. <literal>CURRENT_USER</literal> + and <literal>USER</literal> match the name of the current + user. <literal>PUBLIC</literal> is used to match all present and future user names in the system. </para> </listitem> @@ -82,7 +82,7 @@ DROP USER MAPPING [ IF EXISTS ] FOR { <replaceable class="parameter">user_name</ <title>Examples</title> <para> - Drop a user mapping <literal>bob</>, server <literal>foo</> if it exists: + Drop a user mapping <literal>bob</literal>, server <literal>foo</literal> if it exists: <programlisting> DROP USER MAPPING IF EXISTS FOR bob SERVER foo; </programlisting></para> @@ -93,8 +93,8 @@ DROP USER MAPPING IF EXISTS FOR bob SERVER foo; <para> <command>DROP USER MAPPING</command> conforms to ISO/IEC 9075-9 - (SQL/MED). The <literal>IF EXISTS</> clause is - a <productname>PostgreSQL</> extension. + (SQL/MED). The <literal>IF EXISTS</literal> clause is + a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/drop_view.sgml b/doc/src/sgml/ref/drop_view.sgml index 002d2c6dd65..a33b33335b0 100644 --- a/doc/src/sgml/ref/drop_view.sgml +++ b/doc/src/sgml/ref/drop_view.sgml @@ -97,7 +97,7 @@ DROP VIEW kinds; <para> This command conforms to the SQL standard, except that the standard only allows one view to be dropped per command, and apart from the - <literal>IF EXISTS</> option, which is a <productname>PostgreSQL</> + <literal>IF EXISTS</literal> option, which is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml index 16c49e7928b..9dd44be8828 100644 --- a/doc/src/sgml/ref/dropdb.sgml +++ b/doc/src/sgml/ref/dropdb.sgml @@ -53,7 +53,7 @@ PostgreSQL documentation <title>Options</title> <para> - <application>dropdb</> accepts the following command-line arguments: + <application>dropdb</application> accepts the following command-line arguments: <variablelist> <varlistentry> @@ -66,8 +66,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>dropdb</application> generates @@ -77,8 +77,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-i</></term> - <term><option>--interactive</></term> + <term><option>-i</option></term> + <term><option>--interactive</option></term> <listitem> <para> Issues a verification prompt before doing anything destructive. @@ -87,8 +87,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>dropdb</application> version and exit. @@ -97,7 +97,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--if-exists</></term> + <term><option>--if-exists</option></term> <listitem> <para> Do not throw an error if the database does not exist. A notice is issued @@ -107,8 +107,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>dropdb</application> command line @@ -127,8 +127,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -140,8 +140,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -152,8 +152,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -162,8 +162,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -177,8 +177,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>dropdb</application> to prompt for a @@ -191,14 +191,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>dropdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to in order to drop the @@ -231,8 +231,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml index d7ad61b3d63..1387b7dc2da 100644 --- a/doc/src/sgml/ref/dropuser.sgml +++ b/doc/src/sgml/ref/dropuser.sgml @@ -35,7 +35,7 @@ PostgreSQL documentation <para> <application>dropuser</application> removes an existing <productname>PostgreSQL</productname> user. - Only superusers and users with the <literal>CREATEROLE</> privilege can + Only superusers and users with the <literal>CREATEROLE</literal> privilege can remove <productname>PostgreSQL</productname> users. (To remove a superuser, you must yourself be a superuser.) </para> @@ -70,8 +70,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>dropuser</application> generates @@ -81,8 +81,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-i</></term> - <term><option>--interactive</></term> + <term><option>-i</option></term> + <term><option>--interactive</option></term> <listitem> <para> Prompt for confirmation before actually removing the user, and prompt @@ -92,8 +92,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>dropuser</application> version and exit. @@ -102,7 +102,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--if-exists</></term> + <term><option>--if-exists</option></term> <listitem> <para> Do not throw an error if the user does not exist. A notice is @@ -112,8 +112,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>dropuser</application> command line @@ -131,8 +131,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -144,8 +144,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -156,8 +156,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as (not the user name to drop). @@ -166,8 +166,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -181,8 +181,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>dropuser</application> to prompt for a @@ -195,7 +195,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>dropuser</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -223,8 +223,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/ecpg-ref.sgml b/doc/src/sgml/ref/ecpg-ref.sgml index 8bfb47c4d79..a9eaff815dc 100644 --- a/doc/src/sgml/ref/ecpg-ref.sgml +++ b/doc/src/sgml/ref/ecpg-ref.sgml @@ -220,9 +220,9 @@ PostgreSQL documentation <para> When compiling the preprocessed C code files, the compiler needs to - be able to find the <application>ECPG</> header files in the - <productname>PostgreSQL</> include directory. Therefore, you might - have to use the <option>-I</> option when invoking the compiler + be able to find the <application>ECPG</application> header files in the + <productname>PostgreSQL</productname> include directory. Therefore, you might + have to use the <option>-I</option> option when invoking the compiler (e.g., <literal>-I/usr/local/pgsql/include</literal>). </para> diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml index 10e414515bf..1f74118efd9 100644 --- a/doc/src/sgml/ref/end.sgml +++ b/doc/src/sgml/ref/end.sgml @@ -62,7 +62,7 @@ END [ WORK | TRANSACTION ] </para> <para> - Issuing <command>END</> when not inside a transaction does + Issuing <command>END</command> when not inside a transaction does no harm, but it will provoke a warning message. </para> </refsect1> diff --git a/doc/src/sgml/ref/execute.sgml b/doc/src/sgml/ref/execute.sgml index 6ab5e54fa7e..6ac413d8086 100644 --- a/doc/src/sgml/ref/execute.sgml +++ b/doc/src/sgml/ref/execute.sgml @@ -87,12 +87,12 @@ EXECUTE <replaceable class="parameter">name</replaceable> [ ( <replaceable class <title>Outputs</title> <para> The command tag returned by <command>EXECUTE</command> - is that of the prepared statement, and not <literal>EXECUTE</>. + is that of the prepared statement, and not <literal>EXECUTE</literal>. </para> </refsect1> <refsect1> - <title>Examples</> + <title>Examples</title> <para> Examples are given in the <xref linkend="sql-prepare-examples" endterm="sql-prepare-examples-title"> section of the <xref diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml index 42191809436..bbf2e11cbb9 100644 --- a/doc/src/sgml/ref/explain.sgml +++ b/doc/src/sgml/ref/explain.sgml @@ -160,15 +160,15 @@ ROLLBACK; shared blocks hit, read, dirtied, and written, the number of local blocks hit, read, dirtied, and written, and the number of temp blocks read and written. - A <emphasis>hit</> means that a read was avoided because the block was + A <emphasis>hit</emphasis> 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 temp blocks contain short-term working data used in sorts, hashes, Materialize plan nodes, and similar cases. - The number of blocks <emphasis>dirtied</> indicates the number of + The number of blocks <emphasis>dirtied</emphasis> indicates the number of previously unmodified blocks that were changed by this query; while the - number of blocks <emphasis>written</> indicates the number of + number of blocks <emphasis>written</emphasis> indicates the number of previously-dirtied blocks evicted from cache by this backend during query processing. The number of blocks shown for an @@ -229,9 +229,9 @@ ROLLBACK; <listitem> <para> Specifies whether the selected option should be turned on or off. - You can write <literal>TRUE</literal>, <literal>ON</>, or + You can write <literal>TRUE</literal>, <literal>ON</literal>, or <literal>1</literal> to enable the option, and <literal>FALSE</literal>, - <literal>OFF</>, or <literal>0</literal> to disable it. The + <literal>OFF</literal>, or <literal>0</literal> to disable it. The <replaceable class="parameter">boolean</replaceable> value can also be omitted, in which case <literal>TRUE</literal> is assumed. </para> @@ -242,10 +242,10 @@ ROLLBACK; <term><replaceable class="parameter">statement</replaceable></term> <listitem> <para> - Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>, - <command>DELETE</>, <command>VALUES</>, <command>EXECUTE</>, - <command>DECLARE</>, <command>CREATE TABLE AS</>, or - <command>CREATE MATERIALIZED VIEW AS</> statement, whose execution + Any <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>, + <command>DELETE</command>, <command>VALUES</command>, <command>EXECUTE</command>, + <command>DECLARE</command>, <command>CREATE TABLE AS</command>, or + <command>CREATE MATERIALIZED VIEW AS</command> statement, whose execution plan you wish to see. </para> </listitem> diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml index 7651dcd0f82..fb79a1ac61a 100644 --- a/doc/src/sgml/ref/fetch.sgml +++ b/doc/src/sgml/ref/fetch.sgml @@ -57,20 +57,20 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <para> A cursor has an associated position, which is used by - <command>FETCH</>. The cursor position can be before the first row of the + <command>FETCH</command>. 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 <command>FETCH</> runs off the end of the available rows + retrieved. If <command>FETCH</command> 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. <command>FETCH ALL</> or <command>FETCH BACKWARD - ALL</> will always leave the cursor positioned after the last row or before + row if fetching backward. <command>FETCH ALL</command> or <command>FETCH BACKWARD + ALL</command> will always leave the cursor positioned after the last row or before the first row. </para> <para> - The forms <literal>NEXT</>, <literal>PRIOR</>, <literal>FIRST</>, - <literal>LAST</>, <literal>ABSOLUTE</>, <literal>RELATIVE</> fetch + The forms <literal>NEXT</literal>, <literal>PRIOR</literal>, <literal>FIRST</literal>, + <literal>LAST</literal>, <literal>ABSOLUTE</literal>, <literal>RELATIVE</literal> 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 @@ -78,7 +78,7 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < </para> <para> - The forms using <literal>FORWARD</> and <literal>BACKWARD</> + The forms using <literal>FORWARD</literal> and <literal>BACKWARD</literal> 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 <replaceable @@ -87,8 +87,8 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < </para> <para> - <literal>RELATIVE 0</>, <literal>FORWARD 0</>, and - <literal>BACKWARD 0</> all request fetching the current row without + <literal>RELATIVE 0</literal>, <literal>FORWARD 0</literal>, and + <literal>BACKWARD 0</literal> 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. @@ -97,7 +97,7 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <note> <para> This page describes usage of cursors at the SQL command level. - If you are trying to use cursors inside a <application>PL/pgSQL</> + If you are trying to use cursors inside a <application>PL/pgSQL</application> function, the rules are different — see <xref linkend="plpgsql-cursors">. </para> @@ -274,10 +274,10 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <listitem> <para><replaceable class="parameter">count</replaceable> is a possibly-signed integer constant, determining the location or - number of rows to fetch. For <literal>FORWARD</> and - <literal>BACKWARD</> cases, specifying a negative <replaceable + number of rows to fetch. For <literal>FORWARD</literal> and + <literal>BACKWARD</literal> cases, specifying a negative <replaceable class="parameter">count</replaceable> is equivalent to changing - the sense of <literal>FORWARD</> and <literal>BACKWARD</>. + the sense of <literal>FORWARD</literal> and <literal>BACKWARD</literal>. </para> </listitem> </varlistentry> @@ -297,7 +297,7 @@ FETCH [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] < <title>Outputs</title> <para> - On successful completion, a <command>FETCH</> command returns a command + On successful completion, a <command>FETCH</command> command returns a command tag of the form <screen> FETCH <replaceable class="parameter">count</replaceable> @@ -315,8 +315,8 @@ FETCH <replaceable class="parameter">count</replaceable> <para> The cursor should be declared with the <literal>SCROLL</literal> - option if one intends to use any variants of <command>FETCH</> - other than <command>FETCH NEXT</> or <command>FETCH FORWARD</> with + option if one intends to use any variants of <command>FETCH</command> + other than <command>FETCH NEXT</command> or <command>FETCH FORWARD</command> with a positive count. For simple queries <productname>PostgreSQL</productname> will allow backwards fetch from cursors not declared with <literal>SCROLL</literal>, but this @@ -400,8 +400,8 @@ COMMIT WORK; </para> <para> - The SQL standard allows only <literal>FROM</> preceding the cursor - name; the option to use <literal>IN</>, or to leave them out altogether, is + The SQL standard allows only <literal>FROM</literal> preceding the cursor + name; the option to use <literal>IN</literal>, or to leave them out altogether, is an extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/grant.sgml b/doc/src/sgml/ref/grant.sgml index 385cfe6a9ca..fd9fe03a6ad 100644 --- a/doc/src/sgml/ref/grant.sgml +++ b/doc/src/sgml/ref/grant.sgml @@ -116,7 +116,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace 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, and functions (but note that <literal>ALL - TABLES</> is considered to include views and foreign tables). + TABLES</literal> is considered to include views and foreign tables). </para> <para> @@ -174,7 +174,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace (including domains). The object owner can, of course, <command>REVOKE</command> both default and expressly granted privileges. (For maximum - security, issue the <command>REVOKE</> in the same transaction that + security, issue the <command>REVOKE</command> in the same transaction that creates the object; then there is no window in which another user can use the object.) Also, these initial default privilege settings can be changed using the @@ -211,7 +211,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows <xref linkend="sql-insert"> of a new row into the specified table. If specific columns are listed, - only those columns may be assigned to in the <command>INSERT</> + only those columns may be assigned to in the <command>INSERT</command> command (other columns will therefore receive default values). Also allows <xref linkend="sql-copy"> FROM. </para> @@ -224,8 +224,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows <xref linkend="sql-update"> of any column, or the specific columns listed, of the specified table. - (In practice, any nontrivial <command>UPDATE</> command will require - <literal>SELECT</> privilege as well, since it must reference table + (In practice, any nontrivial <command>UPDATE</command> command will require + <literal>SELECT</literal> privilege as well, since it must reference table columns to determine which rows to update, and/or to compute new values for columns.) <literal>SELECT ... FOR UPDATE</literal> @@ -246,8 +246,8 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows <xref linkend="sql-delete"> of a row from the specified table. - (In practice, any nontrivial <command>DELETE</> command will require - <literal>SELECT</> privilege as well, since it must reference table + (In practice, any nontrivial <command>DELETE</command> command will require + <literal>SELECT</literal> privilege as well, since it must reference table columns to determine which rows to delete.) </para> </listitem> @@ -292,7 +292,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace </para> <para> For schemas, allows new objects to be created within the schema. - To rename an existing object, you must own the object <emphasis>and</> + To rename an existing object, you must own the object <emphasis>and</emphasis> have this privilege for the containing schema. </para> <para> @@ -310,7 +310,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Allows the user to connect to the specified database. This privilege is checked at connection startup (in addition to checking - any restrictions imposed by <filename>pg_hba.conf</>). + any restrictions imposed by <filename>pg_hba.conf</filename>). </para> </listitem> </varlistentry> @@ -348,7 +348,7 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> For schemas, allows access to objects contained in the specified schema (assuming that the objects' own privilege requirements are - also met). Essentially this allows the grantee to <quote>look up</> + also met). Essentially this allows the grantee to <quote>look up</quote> objects within the schema. Without this permission, it is still possible to see the object names, e.g. by querying the system tables. Also, after revoking this permission, existing backends might have @@ -416,14 +416,14 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace OPTION</literal> on itself, but it may grant or revoke membership in itself from a database session where the session user matches the role. Database superusers can grant or revoke membership in any role - to anyone. Roles having <literal>CREATEROLE</> privilege can grant + to anyone. Roles having <literal>CREATEROLE</literal> privilege can grant or revoke membership in any role that is not a superuser. </para> <para> Unlike the case with privileges, membership in a role cannot be granted - to <literal>PUBLIC</>. Note also that this form of the command does not - allow the noise word <literal>GROUP</>. + to <literal>PUBLIC</literal>. Note also that this form of the command does not + allow the noise word <literal>GROUP</literal>. </para> </refsect2> </refsect1> @@ -440,13 +440,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> Since <productname>PostgreSQL</productname> 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 <literal>GROUP</> - to identify whether a grantee is a user or a group. <literal>GROUP</> + It is therefore no longer necessary to use the keyword <literal>GROUP</literal> + to identify whether a grantee is a user or a group. <literal>GROUP</literal> is still allowed in the command, but it is a noise word. </para> <para> - A user may perform <command>SELECT</>, <command>INSERT</>, etc. on a + A user may perform <command>SELECT</command>, <command>INSERT</command>, 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 @@ -454,12 +454,12 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace </para> <para> - When a non-owner of an object attempts to <command>GRANT</> privileges + When a non-owner of an object attempts to <command>GRANT</command> 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 <command>GRANT ALL - PRIVILEGES</> forms will issue a warning message if no grant options are + PRIVILEGES</command> 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 @@ -470,13 +470,13 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace <para> It should be noted that database superusers can access all objects regardless of object privilege settings. This - is comparable to the rights of <literal>root</> in a Unix system. - As with <literal>root</>, it's unwise to operate as a superuser + is comparable to the rights of <literal>root</literal> in a Unix system. + As with <literal>root</literal>, it's unwise to operate as a superuser except when absolutely necessary. </para> <para> - If a superuser chooses to issue a <command>GRANT</> or <command>REVOKE</> + If a superuser chooses to issue a <command>GRANT</command> or <command>REVOKE</command> 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. @@ -485,32 +485,32 @@ GRANT <replaceable class="parameter">role_name</replaceable> [, ...] TO <replace </para> <para> - <command>GRANT</> and <command>REVOKE</> can also be done by a role + <command>GRANT</command> and <command>REVOKE</command> 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 <literal>WITH GRANT OPTION</literal> 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 <literal>WITH GRANT OPTION</literal>. For example, if table - <literal>t1</> is owned by role <literal>g1</>, of which role - <literal>u1</> is a member, then <literal>u1</> can grant privileges - on <literal>t1</> to <literal>u2</>, but those privileges will appear - to have been granted directly by <literal>g1</>. Any other member - of role <literal>g1</> could revoke them later. + <literal>t1</literal> is owned by role <literal>g1</literal>, of which role + <literal>u1</literal> is a member, then <literal>u1</literal> can grant privileges + on <literal>t1</literal> to <literal>u2</literal>, but those privileges will appear + to have been granted directly by <literal>g1</literal>. Any other member + of role <literal>g1</literal> could revoke them later. </para> <para> - If the role executing <command>GRANT</> holds the required privileges + If the role executing <command>GRANT</command> 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 <command>SET ROLE</> to become the - specific role you want to do the <command>GRANT</> as. + cases it is best practice to use <command>SET ROLE</command> to become the + specific role you want to do the <command>GRANT</command> as. </para> <para> Granting permission on a table does not automatically extend permissions to any sequences used by the table, including - sequences tied to <type>SERIAL</> columns. Permissions on + sequences tied to <type>SERIAL</type> columns. Permissions on sequences must be set separately. </para> @@ -551,8 +551,8 @@ rolename=xxxx -- privileges granted to a role /yyyy -- role that granted this privilege </literallayout> - The above example display would be seen by user <literal>miriam</> after - creating table <literal>mytable</> and doing: + The above example display would be seen by user <literal>miriam</literal> after + creating table <literal>mytable</literal> and doing: <programlisting> GRANT SELECT ON mytable TO PUBLIC; @@ -562,31 +562,31 @@ GRANT SELECT (col1), UPDATE (col1) ON mytable TO miriam_rw; </para> <para> - For non-table objects there are other <command>\d</> commands + For non-table objects there are other <command>\d</command> commands that can display their privileges. </para> <para> - If the <quote>Access privileges</> column is empty for a given object, + If the <quote>Access privileges</quote> column is empty for a given object, it means the object has default privileges (that is, its privileges column is null). Default privileges always include all privileges for the owner, - and can include some privileges for <literal>PUBLIC</> depending on the - object type, as explained above. The first <command>GRANT</> or - <command>REVOKE</> on an object + and can include some privileges for <literal>PUBLIC</literal> depending on the + object type, as explained above. The first <command>GRANT</command> or + <command>REVOKE</command> on an object will instantiate the default privileges (producing, for example, - <literal>{miriam=arwdDxt/miriam}</>) and then modify them per the + <literal>{miriam=arwdDxt/miriam}</literal>) and then modify them per the specified request. Similarly, entries are shown in <quote>Column access - privileges</> only for columns with nondefault privileges. - (Note: for this purpose, <quote>default privileges</> always means the + privileges</quote> only for columns with nondefault privileges. + (Note: for this purpose, <quote>default privileges</quote> always means the built-in default privileges for the object's type. An object whose - privileges have been affected by an <command>ALTER DEFAULT PRIVILEGES</> + privileges have been affected by an <command>ALTER DEFAULT PRIVILEGES</command> command will always be shown with an explicit privilege entry that - includes the effects of the <command>ALTER</>.) + includes the effects of the <command>ALTER</command>.) </para> <para> Notice that the owner's implicit grant options are not marked in the - access privileges display. A <literal>*</> will appear only when + access privileges display. A <literal>*</literal> will appear only when grant options have been explicitly granted to someone. </para> </refsect1> @@ -617,7 +617,7 @@ GRANT ALL PRIVILEGES ON kinds TO manuel; </para> <para> - Grant membership in role <literal>admins</> to user <literal>joe</>: + Grant membership in role <literal>admins</literal> to user <literal>joe</literal>: <programlisting> GRANT admins TO joe; @@ -637,14 +637,14 @@ GRANT admins TO joe; <para> <productname>PostgreSQL</productname> 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 <literal>INSERT</>, - <literal>UPDATE</>, <literal>DELETE</>, and <literal>TRUNCATE</> + read-only to themselves by revoking their own <literal>INSERT</literal>, + <literal>UPDATE</literal>, <literal>DELETE</literal>, and <literal>TRUNCATE</literal> privileges. This is not possible according to the SQL standard. The reason is that <productname>PostgreSQL</productname> treats the owner's privileges as having been granted by the owner to themselves; therefore they can revoke them too. In the SQL standard, the owner's privileges are - granted by an assumed entity <quote>_SYSTEM</>. Not being - <quote>_SYSTEM</>, the owner cannot revoke these rights. + granted by an assumed entity <quote>_SYSTEM</quote>. Not being + <quote>_SYSTEM</quote>, the owner cannot revoke these rights. </para> <para> diff --git a/doc/src/sgml/ref/import_foreign_schema.sgml b/doc/src/sgml/ref/import_foreign_schema.sgml index f22893f1373..9bc83f1c6a6 100644 --- a/doc/src/sgml/ref/import_foreign_schema.sgml +++ b/doc/src/sgml/ref/import_foreign_schema.sgml @@ -124,9 +124,9 @@ IMPORT FOREIGN SCHEMA <replaceable class="parameter">remote_schema</replaceable> <title>Examples</title> <para> - Import table definitions from a remote schema <structname>foreign_films</> - on server <structname>film_server</>, creating the foreign tables in - local schema <structname>films</>: + Import table definitions from a remote schema <structname>foreign_films</structname> + on server <structname>film_server</structname>, creating the foreign tables in + local schema <structname>films</structname>: <programlisting> IMPORT FOREIGN SCHEMA foreign_films @@ -135,8 +135,8 @@ IMPORT FOREIGN SCHEMA foreign_films </para> <para> - As above, but import only the two tables <structname>actors</> and - <literal>directors</> (if they exist): + As above, but import only the two tables <structname>actors</structname> and + <literal>directors</literal> (if they exist): <programlisting> IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors) @@ -149,8 +149,8 @@ IMPORT FOREIGN SCHEMA foreign_films LIMIT TO (actors, directors) <para> The <command>IMPORT FOREIGN SCHEMA</command> command conforms to the - <acronym>SQL</acronym> standard, except that the <literal>OPTIONS</> - clause is a <productname>PostgreSQL</> extension. + <acronym>SQL</acronym> standard, except that the <literal>OPTIONS</literal> + clause is a <productname>PostgreSQL</productname> extension. </para> </refsect1> diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 732fecab8ec..6696d4d05ab 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -79,8 +79,8 @@ PostgreSQL documentation <para> <command>initdb</command> initializes the database cluster's default locale and character set encoding. The character set encoding, - collation order (<literal>LC_COLLATE</>) and character set classes - (<literal>LC_CTYPE</>, e.g. upper, lower, digit) can be set separately + collation order (<literal>LC_COLLATE</literal>) and character set classes + (<literal>LC_CTYPE</literal>, e.g. upper, lower, digit) can be set separately for a database when it is created. <command>initdb</command> determines those settings for the <literal>template1</literal> database, which will serve as the default for all other databases. @@ -89,7 +89,7 @@ PostgreSQL documentation <para> To alter the default collation order or character set classes, use the <option>--lc-collate</option> and <option>--lc-ctype</option> options. - Collation orders other than <literal>C</> or <literal>POSIX</> also have + Collation orders other than <literal>C</literal> or <literal>POSIX</literal> also have a performance penalty. For these reasons it is important to choose the right locale when running <command>initdb</command>. </para> @@ -98,8 +98,8 @@ PostgreSQL documentation The remaining locale categories can be changed later when the server is started. You can also use <option>--locale</option> to set the default for all locale categories, including collation order and - character set classes. All server locale values (<literal>lc_*</>) can - be displayed via <command>SHOW ALL</>. + character set classes. All server locale values (<literal>lc_*</literal>) can + be displayed via <command>SHOW ALL</command>. More details can be found in <xref linkend="locale">. </para> @@ -121,7 +121,7 @@ PostgreSQL documentation <listitem> <para> This option specifies the default authentication method for local - users used in <filename>pg_hba.conf</> (<literal>host</literal> + users used in <filename>pg_hba.conf</filename> (<literal>host</literal> and <literal>local</literal> lines). <command>initdb</command> will prepopulate <filename>pg_hba.conf</filename> entries using the specified authentication method for non-replication as well as @@ -129,8 +129,8 @@ PostgreSQL documentation </para> <para> - Do not use <literal>trust</> unless you trust all local users on your - system. <literal>trust</> is the default for ease of installation. + Do not use <literal>trust</literal> unless you trust all local users on your + system. <literal>trust</literal> is the default for ease of installation. </para> </listitem> </varlistentry> @@ -140,7 +140,7 @@ PostgreSQL documentation <listitem> <para> This option specifies the authentication method for local users via - TCP/IP connections used in <filename>pg_hba.conf</> + TCP/IP connections used in <filename>pg_hba.conf</filename> (<literal>host</literal> lines). </para> </listitem> @@ -151,7 +151,7 @@ PostgreSQL documentation <listitem> <para> This option specifies the authentication method for local users via - Unix-domain socket connections used in <filename>pg_hba.conf</> + Unix-domain socket connections used in <filename>pg_hba.conf</filename> (<literal>local</literal> lines). </para> </listitem> @@ -255,7 +255,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--pwfile=<replaceable>filename</></option></term> + <term><option>--pwfile=<replaceable>filename</replaceable></option></term> <listitem> <para> Makes <command>initdb</command> read the database superuser's password @@ -270,14 +270,14 @@ PostgreSQL documentation <listitem> <para> Safely write all database files to disk and exit. This does not - perform any of the normal <application>initdb</> operations. + perform any of the normal <application>initdb</application> operations. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-T <replaceable>config</></option></term> - <term><option>--text-search-config=<replaceable>config</></option></term> + <term><option>-T <replaceable>config</replaceable></option></term> + <term><option>--text-search-config=<replaceable>config</replaceable></option></term> <listitem> <para> Sets the default text search configuration. @@ -319,7 +319,7 @@ PostgreSQL documentation <term><option>--wal-segsize=<replaceable>SEGSIZE</replaceable></option></term> <listitem> <para> - Set the <firstterm>WAL segment size</>, in megabytes. This is + Set the <firstterm>WAL segment size</firstterm>, in megabytes. This is the size of each individual file in the WAL log. It may be useful to adjust this size to control the granularity of WAL log shipping. This option can only be set during initialization, and cannot be @@ -395,8 +395,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>initdb</application> version and exit. @@ -405,8 +405,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>initdb</application> command line @@ -449,8 +449,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml index ce037e59027..7f44ec31d15 100644 --- a/doc/src/sgml/ref/insert.sgml +++ b/doc/src/sgml/ref/insert.sgml @@ -56,10 +56,10 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <para> 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 <replaceable>N</> column - names, if there are only <replaceable>N</> columns supplied by the - <literal>VALUES</> clause or <replaceable>query</>. The values - supplied by the <literal>VALUES</> clause or <replaceable>query</> are + table in their declared order; or the first <replaceable>N</replaceable> column + names, if there are only <replaceable>N</replaceable> columns supplied by the + <literal>VALUES</literal> clause or <replaceable>query</replaceable>. The values + supplied by the <literal>VALUES</literal> clause or <replaceable>query</replaceable> are associated with the explicit or implicit column list left-to-right. </para> @@ -75,21 +75,21 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac </para> <para> - <literal>ON CONFLICT</> can be used to specify an alternative + <literal>ON CONFLICT</literal> can be used to specify an alternative action to raising a unique constraint or exclusion constraint violation error. (See <xref linkend="sql-on-conflict" endterm="sql-on-conflict-title"> below.) </para> <para> - The optional <literal>RETURNING</> clause causes <command>INSERT</> + The optional <literal>RETURNING</literal> clause causes <command>INSERT</command> to compute and return value(s) based on each row actually inserted - (or updated, if an <literal>ON CONFLICT DO UPDATE</> clause was + (or updated, if an <literal>ON CONFLICT DO UPDATE</literal> 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's columns is allowed. The syntax of - the <literal>RETURNING</> list is identical to that of the output - list of <command>SELECT</>. Only rows that were successfully + the <literal>RETURNING</literal> list is identical to that of the output + list of <command>SELECT</command>. Only rows that were successfully inserted or updated will be returned. For example, if a row was locked but not updated because an <literal>ON CONFLICT DO UPDATE ... WHERE</literal> clause <replaceable @@ -99,7 +99,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <para> You must have <literal>INSERT</literal> privilege on a table in - order to insert into it. If <literal>ON CONFLICT DO UPDATE</> is + order to insert into it. If <literal>ON CONFLICT DO UPDATE</literal> is present, <literal>UPDATE</literal> privilege on the table is also required. </para> @@ -107,17 +107,17 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <para> If a column list is specified, you only need <literal>INSERT</literal> privilege on the listed columns. - Similarly, when <literal>ON CONFLICT DO UPDATE</> is specified, you - only need <literal>UPDATE</> privilege on the column(s) that are - listed to be updated. However, <literal>ON CONFLICT DO UPDATE</> - also requires <literal>SELECT</> privilege on any column whose - values are read in the <literal>ON CONFLICT DO UPDATE</> - expressions or <replaceable>condition</>. + Similarly, when <literal>ON CONFLICT DO UPDATE</literal> is specified, you + only need <literal>UPDATE</literal> privilege on the column(s) that are + listed to be updated. However, <literal>ON CONFLICT DO UPDATE</literal> + also requires <literal>SELECT</literal> privilege on any column whose + values are read in the <literal>ON CONFLICT DO UPDATE</literal> + expressions or <replaceable>condition</replaceable>. </para> <para> - Use of the <literal>RETURNING</> clause requires <literal>SELECT</> - privilege on all columns mentioned in <literal>RETURNING</>. + Use of the <literal>RETURNING</literal> clause requires <literal>SELECT</literal> + privilege on all columns mentioned in <literal>RETURNING</literal>. If you use the <replaceable class="parameter">query</replaceable> clause to insert rows from a query, you of course need to have <literal>SELECT</literal> privilege on @@ -144,7 +144,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <listitem> <para> The <literal>WITH</literal> clause allows you to specify one or more - subqueries that can be referenced by name in the <command>INSERT</> + subqueries that can be referenced by name in the <command>INSERT</command> query. See <xref linkend="queries-with"> and <xref linkend="sql-select"> for details. </para> @@ -175,8 +175,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac A substitute name for <replaceable class="parameter">table_name</replaceable>. When an alias is provided, it completely hides the actual name of the table. - This is particularly useful when <literal>ON CONFLICT DO UPDATE</> - targets a table named <varname>excluded</>, since that will otherwise + This is particularly useful when <literal>ON CONFLICT DO UPDATE</literal> + targets a table named <varname>excluded</varname>, since that will otherwise be taken as the name of the special table representing rows proposed for insertion. </para> @@ -193,11 +193,11 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac 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 <literal>ON CONFLICT DO UPDATE</>, do not include + column with <literal>ON CONFLICT DO UPDATE</literal>, do not include the table's name in the specification of a target column. For example, <literal>INSERT INTO table_name ... ON CONFLICT DO UPDATE - SET table_name.col = 1</> is invalid (this follows the general - behavior for <command>UPDATE</>). + SET table_name.col = 1</literal> is invalid (this follows the general + behavior for <command>UPDATE</command>). </para> </listitem> </varlistentry> @@ -281,11 +281,11 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <listitem> <para> An expression to be computed and returned by the - <command>INSERT</> command after each row is inserted or + <command>INSERT</command> command after each row is inserted or updated. The expression can use any column names of the table named by <replaceable class="parameter">table_name</replaceable>. Write - <literal>*</> to return all columns of the inserted or updated + <literal>*</literal> to return all columns of the inserted or updated row(s). </para> </listitem> @@ -386,7 +386,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac UPDATE</literal> have access to the existing row using the table's name (or an alias), and to rows proposed for insertion using the special <varname>excluded</varname> table. - <literal>SELECT</> privilege is required on any column in the + <literal>SELECT</literal> privilege is required on any column in the target table where corresponding <varname>excluded</varname> columns are read. </para> @@ -406,7 +406,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac The name of a <replaceable class="parameter">table_name</replaceable> column. Used to infer arbiter indexes. Follows <command>CREATE - INDEX</command> format. <literal>SELECT</> privilege on + INDEX</command> format. <literal>SELECT</literal> privilege on <replaceable class="parameter">index_column_name</replaceable> is required. </para> @@ -422,7 +422,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac infer expressions on <replaceable class="parameter">table_name</replaceable> columns appearing within index definitions (not simple columns). Follows - <command>CREATE INDEX</command> format. <literal>SELECT</> + <command>CREATE INDEX</command> format. <literal>SELECT</literal> privilege on any column appearing within <replaceable class="parameter">index_expression</replaceable> is required. </para> @@ -469,7 +469,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac 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 <command>CREATE - INDEX</command> format. <literal>SELECT</> privilege on any + INDEX</command> format. <literal>SELECT</literal> privilege on any column appearing within <replaceable class="parameter">index_predicate</replaceable> is required. </para> @@ -494,7 +494,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac An expression that returns a value of type <type>boolean</type>. Only rows for which this expression returns <literal>true</literal> will be updated, although all - rows will be locked when the <literal>ON CONFLICT DO UPDATE</> + rows will be locked when the <literal>ON CONFLICT DO UPDATE</literal> action is taken. Note that <replaceable>condition</replaceable> is evaluated last, after a conflict has been identified as a candidate to update. @@ -510,7 +510,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac </para> <para> - <command>INSERT</command> with an <literal>ON CONFLICT DO UPDATE</> + <command>INSERT</command> with an <literal>ON CONFLICT DO UPDATE</literal> clause is a <quote>deterministic</quote> 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 @@ -538,7 +538,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac <title>Outputs</title> <para> - On successful completion, an <command>INSERT</> command returns a command + On successful completion, an <command>INSERT</command> command returns a command tag of the form <screen> INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable> @@ -554,10 +554,10 @@ INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</repl </para> <para> - If the <command>INSERT</> command contains a <literal>RETURNING</> - clause, the result will be similar to that of a <command>SELECT</> + If the <command>INSERT</command> command contains a <literal>RETURNING</literal> + clause, the result will be similar to that of a <command>SELECT</command> statement containing the columns and values defined in the - <literal>RETURNING</> list, computed over the row(s) inserted or + <literal>RETURNING</literal> list, computed over the row(s) inserted or updated by the command. </para> </refsect1> @@ -616,7 +616,7 @@ INSERT INTO films DEFAULT VALUES; </para> <para> - To insert multiple rows using the multirow <command>VALUES</> syntax: + To insert multiple rows using the multirow <command>VALUES</command> syntax: <programlisting> INSERT INTO films (code, title, did, date_prod, kind) VALUES @@ -675,7 +675,7 @@ INSERT INTO employees_log SELECT *, current_timestamp FROM upd; Insert or update new distributors as appropriate. Assumes a unique index has been defined that constrains values appearing in the <literal>did</literal> column. Note that the special - <varname>excluded</> table is used to reference values originally + <varname>excluded</varname> table is used to reference values originally proposed for insertion: <programlisting> INSERT INTO distributors (did, dname) @@ -697,7 +697,7 @@ INSERT INTO distributors (did, dname) VALUES (7, 'Redline GmbH') <para> Insert or update new distributors as appropriate. Example assumes a unique index has been defined that constrains values appearing in - the <literal>did</literal> column. <literal>WHERE</> clause is + the <literal>did</literal> column. <literal>WHERE</literal> clause is used to limit the rows actually updated (any existing row not updated will still be locked, though): <programlisting> @@ -734,13 +734,13 @@ INSERT INTO distributors (did, dname) VALUES (10, 'Conrad International') <para> <command>INSERT</command> conforms to the SQL standard, except that - the <literal>RETURNING</> clause is a + the <literal>RETURNING</literal> clause is a <productname>PostgreSQL</productname> extension, as is the ability - to use <literal>WITH</> with <command>INSERT</>, and the ability to - specify an alternative action with <literal>ON CONFLICT</>. + to use <literal>WITH</literal> with <command>INSERT</command>, and the ability to + specify an alternative action with <literal>ON CONFLICT</literal>. Also, the case in which a column name list is omitted, but not all the columns are - filled from the <literal>VALUES</> clause or <replaceable>query</>, + filled from the <literal>VALUES</literal> clause or <replaceable>query</replaceable>, is disallowed by the standard. </para> diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml index 76215716d61..65275627174 100644 --- a/doc/src/sgml/ref/listen.sgml +++ b/doc/src/sgml/ref/listen.sgml @@ -54,12 +54,12 @@ LISTEN <replaceable class="parameter">channel</replaceable> <para> The method a client application must use to detect notification events depends on which <productname>PostgreSQL</productname> application programming interface it - uses. With the <application>libpq</> library, the application issues + uses. With the <application>libpq</application> library, the application issues <command>LISTEN</command> as an ordinary SQL command, and then must periodically call the function <function>PQnotifies</function> to find out whether any notification events have been received. Other interfaces such as - <application>libpgtcl</> provide higher-level methods for handling notify events; indeed, - with <application>libpgtcl</> the application programmer should not even issue + <application>libpgtcl</application> provide higher-level methods for handling notify events; indeed, + with <application>libpgtcl</application> the application programmer should not even issue <command>LISTEN</command> or <command>UNLISTEN</command> directly. See the documentation for the interface you are using for more details. </para> diff --git a/doc/src/sgml/ref/load.sgml b/doc/src/sgml/ref/load.sgml index 2be28e6d15a..b9e3fe8b255 100644 --- a/doc/src/sgml/ref/load.sgml +++ b/doc/src/sgml/ref/load.sgml @@ -28,12 +28,12 @@ LOAD '<replaceable class="parameter">filename</replaceable>' <title>Description</title> <para> - This command loads a shared library file into the <productname>PostgreSQL</> + This command loads a shared library file into the <productname>PostgreSQL</productname> server's 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 <command>LOAD</> is usually only needed to - load a library that modifies the server's behavior through <quote>hooks</> + Therefore, an explicit <command>LOAD</command> is usually only needed to + load a library that modifies the server's behavior through <quote>hooks</quote> rather than providing a set of functions. </para> @@ -47,15 +47,15 @@ LOAD '<replaceable class="parameter">filename</replaceable>' </para> <indexterm> - <primary><filename>$libdir/plugins</></primary> + <primary><filename>$libdir/plugins</filename></primary> </indexterm> <para> - Non-superusers can only apply <command>LOAD</> to library files - located in <filename>$libdir/plugins/</> — the specified + Non-superusers can only apply <command>LOAD</command> to library files + located in <filename>$libdir/plugins/</filename> — the specified <replaceable class="parameter">filename</replaceable> must begin with exactly that string. (It is the database administrator's - responsibility to ensure that only <quote>safe</> libraries + responsibility to ensure that only <quote>safe</quote> libraries are installed there.) </para> </refsect1> diff --git a/doc/src/sgml/ref/lock.sgml b/doc/src/sgml/ref/lock.sgml index f1dbb8e65a8..6d68ec6c53b 100644 --- a/doc/src/sgml/ref/lock.sgml +++ b/doc/src/sgml/ref/lock.sgml @@ -51,13 +51,13 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] restrictive lock mode possible. <command>LOCK TABLE</command> provides for cases when you might need more restrictive locking. For example, suppose an application runs a transaction at the - <literal>READ COMMITTED</> isolation level and needs to ensure that + <literal>READ COMMITTED</literal> 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 <literal>SHARE</> lock mode over the + To achieve this you could obtain <literal>SHARE</literal> 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 <literal>SHARE</> lock mode conflicts with - the <literal>ROW EXCLUSIVE</> lock acquired by writers, and your + committed data, because <literal>SHARE</literal> lock mode conflicts with + the <literal>ROW EXCLUSIVE</literal> lock acquired by writers, and your <command>LOCK TABLE <replaceable class="parameter">name</replaceable> IN SHARE MODE</command> statement will wait until any concurrent holders of <literal>ROW @@ -68,28 +68,28 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <para> To achieve a similar effect when running a transaction at the - <literal>REPEATABLE READ</> or <literal>SERIALIZABLE</> - isolation level, you have to execute the <command>LOCK TABLE</> statement - before executing any <command>SELECT</> or data modification statement. - A <literal>REPEATABLE READ</> or <literal>SERIALIZABLE</> transaction's + <literal>REPEATABLE READ</literal> or <literal>SERIALIZABLE</literal> + isolation level, you have to execute the <command>LOCK TABLE</command> statement + before executing any <command>SELECT</command> or data modification statement. + A <literal>REPEATABLE READ</literal> or <literal>SERIALIZABLE</literal> transaction's view of data will be frozen when its first - <command>SELECT</> or data modification statement begins. A <command>LOCK - TABLE</> later in the transaction will still prevent concurrent writes + <command>SELECT</command> or data modification statement begins. A <command>LOCK + TABLE</command> later in the transaction will still prevent concurrent writes — but it won't ensure that what the transaction reads corresponds to the latest committed values. </para> <para> If a transaction of this sort is going to change the data in the - table, then it should use <literal>SHARE ROW EXCLUSIVE</> lock mode - instead of <literal>SHARE</> mode. This ensures that only one + table, then it should use <literal>SHARE ROW EXCLUSIVE</literal> lock mode + instead of <literal>SHARE</literal> 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 <literal>SHARE</> - mode, and then be unable to also acquire <literal>ROW EXCLUSIVE</> + is possible: two transactions might both acquire <literal>SHARE</literal> + mode, and then be unable to also acquire <literal>ROW EXCLUSIVE</literal> mode to actually perform their updates. (Note that a transaction's own locks never conflict, so a transaction can acquire <literal>ROW - EXCLUSIVE</> mode when it holds <literal>SHARE</> mode — but not - if anyone else holds <literal>SHARE</> mode.) To avoid deadlocks, + EXCLUSIVE</literal> mode when it holds <literal>SHARE</literal> mode — but not + if anyone else holds <literal>SHARE</literal> 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 @@ -111,16 +111,16 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <listitem> <para> The name (optionally schema-qualified) of an existing table to - lock. If <literal>ONLY</> is specified before the table name, only that - table is locked. If <literal>ONLY</> is not specified, the table and all - its descendant tables (if any) are locked. Optionally, <literal>*</> + lock. If <literal>ONLY</literal> is specified before the table name, only that + table is locked. If <literal>ONLY</literal> is not specified, the table and all + its descendant tables (if any) are locked. Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> <para> - The command <literal>LOCK TABLE a, b;</> is equivalent to - <literal>LOCK TABLE a; LOCK TABLE b;</>. The tables are locked + The command <literal>LOCK TABLE a, b;</literal> is equivalent to + <literal>LOCK TABLE a; LOCK TABLE b;</literal>. The tables are locked one-by-one in the order specified in the <command>LOCK TABLE</command> command. </para> @@ -160,18 +160,18 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <title>Notes</title> <para> - <literal>LOCK TABLE ... IN ACCESS SHARE MODE</> requires <literal>SELECT</> + <literal>LOCK TABLE ... IN ACCESS SHARE MODE</literal> requires <literal>SELECT</literal> privileges on the target table. <literal>LOCK TABLE ... IN ROW EXCLUSIVE - MODE</> requires <literal>INSERT</>, <literal>UPDATE</>, <literal>DELETE</>, - or <literal>TRUNCATE</> privileges on the target table. All other forms of - <command>LOCK</> require table-level <literal>UPDATE</>, <literal>DELETE</>, - or <literal>TRUNCATE</> privileges. + MODE</literal> requires <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>DELETE</literal>, + or <literal>TRUNCATE</literal> privileges on the target table. All other forms of + <command>LOCK</command> require table-level <literal>UPDATE</literal>, <literal>DELETE</literal>, + or <literal>TRUNCATE</literal> privileges. </para> <para> - <command>LOCK TABLE</> is useless outside a transaction block: the lock + <command>LOCK TABLE</command> is useless outside a transaction block: the lock would remain held only to the completion of the statement. Therefore - <productname>PostgreSQL</productname> reports an error if <command>LOCK</> + <productname>PostgreSQL</productname> reports an error if <command>LOCK</command> is used outside a transaction block. Use <xref linkend="sql-begin"> and @@ -181,13 +181,13 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] </para> <para> - <command>LOCK TABLE</> only deals with table-level locks, and so - the mode names involving <literal>ROW</> are all misnomers. These + <command>LOCK TABLE</command> only deals with table-level locks, and so + the mode names involving <literal>ROW</literal> 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, - <literal>ROW EXCLUSIVE</> mode is a shareable table lock. Keep in + <literal>ROW EXCLUSIVE</literal> mode is a shareable table lock. Keep in mind that all the lock modes have identical semantics so far as - <command>LOCK TABLE</> is concerned, differing only in the rules + <command>LOCK TABLE</command> 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 <xref linkend="locking-rows"> and the <xref linkend="sql-for-update-share" @@ -200,7 +200,7 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ] <title>Examples</title> <para> - Obtain a <literal>SHARE</> lock on a primary key table when going to perform + Obtain a <literal>SHARE</literal> lock on a primary key table when going to perform inserts into a foreign key table: <programlisting> @@ -216,7 +216,7 @@ COMMIT WORK; </para> <para> - Take a <literal>SHARE ROW EXCLUSIVE</> lock on a primary key table when going to perform + Take a <literal>SHARE ROW EXCLUSIVE</literal> lock on a primary key table when going to perform a delete operation: <programlisting> @@ -240,8 +240,8 @@ COMMIT WORK; </para> <para> - Except for <literal>ACCESS SHARE</>, <literal>ACCESS EXCLUSIVE</>, - and <literal>SHARE UPDATE EXCLUSIVE</> lock modes, the + Except for <literal>ACCESS SHARE</literal>, <literal>ACCESS EXCLUSIVE</literal>, + and <literal>SHARE UPDATE EXCLUSIVE</literal> lock modes, the <productname>PostgreSQL</productname> lock modes and the <command>LOCK TABLE</command> syntax are compatible with those present in <productname>Oracle</productname>. diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml index 6b809b961d6..4bf78968588 100644 --- a/doc/src/sgml/ref/move.sgml +++ b/doc/src/sgml/ref/move.sgml @@ -69,7 +69,7 @@ MOVE [ <replaceable class="parameter">direction</replaceable> [ FROM | IN ] ] <r <title>Outputs</title> <para> - On successful completion, a <command>MOVE</> command returns a command + On successful completion, a <command>MOVE</command> command returns a command tag of the form <screen> MOVE <replaceable class="parameter">count</replaceable> diff --git a/doc/src/sgml/ref/notify.sgml b/doc/src/sgml/ref/notify.sgml index 09debd6685f..4376b9fdd73 100644 --- a/doc/src/sgml/ref/notify.sgml +++ b/doc/src/sgml/ref/notify.sgml @@ -30,9 +30,9 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla <para> The <command>NOTIFY</command> command sends a notification event together - with an optional <quote>payload</> string to each client application that + with an optional <quote>payload</quote> string to each client application that has previously executed - <command>LISTEN <replaceable class="parameter">channel</></command> + <command>LISTEN <replaceable class="parameter">channel</replaceable></command> for the specified channel name in the current database. Notifications are visible to all users. </para> @@ -49,7 +49,7 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla <para> The information passed to the client for a notification event includes the notification channel - name, the notifying session's server process <acronym>PID</>, and the + name, the notifying session's server process <acronym>PID</acronym>, and the payload string, which is an empty string if it has not been specified. </para> @@ -115,9 +115,9 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla 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's server process <acronym>PID</> (supplied in the + session's server process <acronym>PID</acronym> (supplied in the notification event message) is the same as one's own session's - <acronym>PID</> (available from <application>libpq</>). When they + <acronym>PID</acronym> (available from <application>libpq</application>). When they are the same, the notification event is one's own work bouncing back, and can be ignored. </para> @@ -139,7 +139,7 @@ NOTIFY <replaceable class="parameter">channel</replaceable> [ , <replaceable cla <term><replaceable class="parameter">payload</replaceable></term> <listitem> <para> - The <quote>payload</> string to be communicated along with the + The <quote>payload</quote> 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, diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index f790c560034..1944c185cb9 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <cmdsynopsis> <command>pg_basebackup</command> - <arg rep="repeat"><replaceable>option</></arg> + <arg rep="repeat"><replaceable>option</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -69,7 +69,7 @@ PostgreSQL documentation <application>pg_basebackup</application> can make a base backup from not only the master but also the standby. To take a backup from the standby, set up the standby so that it can accept replication connections (that is, set - <varname>max_wal_senders</> and <xref linkend="guc-hot-standby">, + <varname>max_wal_senders</varname> and <xref linkend="guc-hot-standby">, and configure <link linkend="auth-pg-hba-conf">host-based authentication</link>). You will also need to enable <xref linkend="guc-full-page-writes"> on the master. </para> @@ -85,7 +85,7 @@ PostgreSQL documentation </listitem> <listitem> <para> - If you are using <literal>-X none</>, there is no guarantee that all + If you are using <literal>-X none</literal>, there is no guarantee that all WAL files required for the backup are archived at the end of backup. </para> </listitem> @@ -97,9 +97,9 @@ PostgreSQL documentation <listitem> <para> All WAL records required for the backup must contain sufficient full-page writes, - which requires you to enable <varname>full_page_writes</> on the master and - not to use a tool like <application>pg_compresslog</> as - <varname>archive_command</> to remove full-page writes from WAL files. + which requires you to enable <varname>full_page_writes</varname> on the master and + not to use a tool like <application>pg_compresslog</application> as + <varname>archive_command</varname> to remove full-page writes from WAL files. </para> </listitem> </itemizedlist> @@ -193,8 +193,8 @@ PostgreSQL documentation <listitem> <para> The maximum transfer rate of data transferred from the server. Values are - in kilobytes per second. Use a suffix of <literal>M</> to indicate megabytes - per second. A suffix of <literal>k</> is also accepted, and has no effect. + in kilobytes per second. Use a suffix of <literal>M</literal> to indicate megabytes + per second. A suffix of <literal>k</literal> is also accepted, and has no effect. Valid values are between 32 kilobytes per second and 1024 megabytes per second. </para> <para> @@ -534,7 +534,7 @@ PostgreSQL documentation string. See <xref linkend="libpq-connstring"> for more information. </para> <para> - The option is called <literal>--dbname</> for consistency with other + The option is called <literal>--dbname</literal> for consistency with other client applications, but because <application>pg_basebackup</application> doesn't connect to any particular database in the cluster, database name in the connection string will be ignored. @@ -594,8 +594,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -623,7 +623,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>pg_basebackup</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -636,8 +636,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_basebackup</application> version and exit. @@ -646,8 +646,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_basebackup</application> command line @@ -665,8 +665,8 @@ PostgreSQL documentation <title>Environment</title> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -709,8 +709,8 @@ PostgreSQL documentation tar file before starting the PostgreSQL server. If there are additional tablespaces, the tar files for them need to be unpacked in the correct locations. In this case the symbolic links for those tablespaces will be created by the server - according to the contents of the <filename>tablespace_map</> file that is - included in the <filename>base.tar</> file. + according to the contents of the <filename>tablespace_map</filename> file that is + included in the <filename>base.tar</filename> file. </para> <para> diff --git a/doc/src/sgml/ref/pg_config-ref.sgml b/doc/src/sgml/ref/pg_config-ref.sgml index 0210f6389dc..b819f3f3457 100644 --- a/doc/src/sgml/ref/pg_config-ref.sgml +++ b/doc/src/sgml/ref/pg_config-ref.sgml @@ -13,7 +13,7 @@ <refnamediv> <refname>pg_config</refname> - <refpurpose>retrieve information about the installed version of <productname>PostgreSQL</></refpurpose> + <refpurpose>retrieve information about the installed version of <productname>PostgreSQL</productname></refpurpose> </refnamediv> <refsynopsisdiv> @@ -24,12 +24,12 @@ </refsynopsisdiv> <refsect1> - <title>Description</> + <title>Description</title> <para> - The <application>pg_config</> utility prints configuration parameters - of the currently installed version of <productname>PostgreSQL</>. It is + The <application>pg_config</application> utility prints configuration parameters + of the currently installed version of <productname>PostgreSQL</productname>. It is intended, for example, to be used by software packages that want to interface - to <productname>PostgreSQL</> to facilitate finding the required header files + to <productname>PostgreSQL</productname> to facilitate finding the required header files and libraries. </para> </refsect1> @@ -39,22 +39,22 @@ <title>Options</title> <para> - To use <application>pg_config</>, supply one or more of the following + To use <application>pg_config</application>, supply one or more of the following options: <variablelist> <varlistentry> - <term><option>--bindir</option></> + <term><option>--bindir</option></term> <listitem> <para> Print the location of user executables. Use this, for example, to find - the <command>psql</> program. This is normally also the location - where the <filename>pg_config</> program resides. + the <command>psql</command> program. This is normally also the location + where the <filename>pg_config</filename> program resides. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--docdir</option></> + <term><option>--docdir</option></term> <listitem> <para> Print the location of documentation files. @@ -63,7 +63,7 @@ </varlistentry> <varlistentry> - <term><option>--htmldir</option></> + <term><option>--htmldir</option></term> <listitem> <para> Print the location of HTML documentation files. @@ -72,7 +72,7 @@ </varlistentry> <varlistentry> - <term><option>--includedir</option></> + <term><option>--includedir</option></term> <listitem> <para> Print the location of C header files of the client interfaces. @@ -81,7 +81,7 @@ </varlistentry> <varlistentry> - <term><option>--pkgincludedir</option></> + <term><option>--pkgincludedir</option></term> <listitem> <para> Print the location of other C header files. @@ -90,7 +90,7 @@ </varlistentry> <varlistentry> - <term><option>--includedir-server</option></> + <term><option>--includedir-server</option></term> <listitem> <para> Print the location of C header files for server programming. @@ -99,7 +99,7 @@ </varlistentry> <varlistentry> - <term><option>--libdir</option></> + <term><option>--libdir</option></term> <listitem> <para> Print the location of object code libraries. @@ -108,7 +108,7 @@ </varlistentry> <varlistentry> - <term><option>--pkglibdir</option></> + <term><option>--pkglibdir</option></term> <listitem> <para> Print the location of dynamically loadable modules, or where @@ -120,18 +120,18 @@ </varlistentry> <varlistentry> - <term><option>--localedir</option></> + <term><option>--localedir</option></term> <listitem> <para> Print the location of locale support files. (This will be an empty string if locale support was not configured when - <productname>PostgreSQL</> was built.) + <productname>PostgreSQL</productname> was built.) </para> </listitem> </varlistentry> <varlistentry> - <term><option>--mandir</option></> + <term><option>--mandir</option></term> <listitem> <para> Print the location of manual pages. @@ -140,7 +140,7 @@ </varlistentry> <varlistentry> - <term><option>--sharedir</option></> + <term><option>--sharedir</option></term> <listitem> <para> Print the location of architecture-independent support files. @@ -149,7 +149,7 @@ </varlistentry> <varlistentry> - <term><option>--sysconfdir</option></> + <term><option>--sysconfdir</option></term> <listitem> <para> Print the location of system-wide configuration files. @@ -158,7 +158,7 @@ </varlistentry> <varlistentry> - <term><option>--pgxs</option></> + <term><option>--pgxs</option></term> <listitem> <para> Print the location of extension makefiles. @@ -167,11 +167,11 @@ </varlistentry> <varlistentry> - <term><option>--configure</option></> + <term><option>--configure</option></term> <listitem> <para> - Print the options that were given to the <filename>configure</> - script when <productname>PostgreSQL</> was configured for building. + Print the options that were given to the <filename>configure</filename> + script when <productname>PostgreSQL</productname> was configured for building. This can be used to reproduce the identical configuration, or to find out with what options a binary package was built. (Note however that binary packages often contain vendor-specific custom @@ -181,102 +181,102 @@ </varlistentry> <varlistentry> - <term><option>--cc</option></> + <term><option>--cc</option></term> <listitem> <para> Print the value of the <varname>CC</varname> variable that was used for building - <productname>PostgreSQL</>. This shows the C compiler used. + <productname>PostgreSQL</productname>. This shows the C compiler used. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--cppflags</option></> + <term><option>--cppflags</option></term> <listitem> <para> Print the value of the <varname>CPPFLAGS</varname> variable that was used for building - <productname>PostgreSQL</>. This shows C compiler switches needed - at preprocessing time (typically, <literal>-I</> switches). + <productname>PostgreSQL</productname>. This shows C compiler switches needed + at preprocessing time (typically, <literal>-I</literal> switches). </para> </listitem> </varlistentry> <varlistentry> - <term><option>--cflags</option></> + <term><option>--cflags</option></term> <listitem> <para> Print the value of the <varname>CFLAGS</varname> variable that was used for building - <productname>PostgreSQL</>. This shows C compiler switches. + <productname>PostgreSQL</productname>. This shows C compiler switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--cflags_sl</option></> + <term><option>--cflags_sl</option></term> <listitem> <para> Print the value of the <varname>CFLAGS_SL</varname> variable that was used for building - <productname>PostgreSQL</>. This shows extra C compiler switches + <productname>PostgreSQL</productname>. This shows extra C compiler switches used for building shared libraries. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--ldflags</option></> + <term><option>--ldflags</option></term> <listitem> <para> Print the value of the <varname>LDFLAGS</varname> variable that was used for building - <productname>PostgreSQL</>. This shows linker switches. + <productname>PostgreSQL</productname>. This shows linker switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--ldflags_ex</option></> + <term><option>--ldflags_ex</option></term> <listitem> <para> Print the value of the <varname>LDFLAGS_EX</varname> variable that was used for building - <productname>PostgreSQL</>. This shows linker switches + <productname>PostgreSQL</productname>. This shows linker switches used for building executables only. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--ldflags_sl</option></> + <term><option>--ldflags_sl</option></term> <listitem> <para> Print the value of the <varname>LDFLAGS_SL</varname> variable that was used for building - <productname>PostgreSQL</>. This shows linker switches + <productname>PostgreSQL</productname>. This shows linker switches used for building shared libraries only. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--libs</option></> + <term><option>--libs</option></term> <listitem> <para> Print the value of the <varname>LIBS</varname> variable that was used for building - <productname>PostgreSQL</>. This normally contains <literal>-l</> - switches for external libraries linked into <productname>PostgreSQL</>. + <productname>PostgreSQL</productname>. This normally contains <literal>-l</literal> + switches for external libraries linked into <productname>PostgreSQL</productname>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--version</option></> + <term><option>--version</option></term> <listitem> <para> - Print the version of <productname>PostgreSQL</>. + Print the version of <productname>PostgreSQL</productname>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_config</application> command line @@ -303,9 +303,9 @@ <option>--cc</option>, <option>--cppflags</option>, <option>--cflags</option>, <option>--cflags_sl</option>, <option>--ldflags</option>, <option>--ldflags_sl</option>, - and <option>--libs</option> were added in <productname>PostgreSQL</> 8.1. - The option <option>--htmldir</option> was added in <productname>PostgreSQL</> 8.4. - The option <option>--ldflags_ex</option> was added in <productname>PostgreSQL</> 9.0. + and <option>--libs</option> were added in <productname>PostgreSQL</productname> 8.1. + The option <option>--htmldir</option> was added in <productname>PostgreSQL</productname> 8.4. + The option <option>--ldflags_ex</option> was added in <productname>PostgreSQL</productname> 9.0. </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml index 4a360d61fd3..4d4feacb931 100644 --- a/doc/src/sgml/ref/pg_controldata.sgml +++ b/doc/src/sgml/ref/pg_controldata.sgml @@ -31,7 +31,7 @@ PostgreSQL documentation <title>Description</title> <para> <command>pg_controldata</command> prints information initialized during - <command>initdb</>, such as the catalog version. + <command>initdb</command>, such as the catalog version. It also shows information about write-ahead logging and checkpoint processing. This information is cluster-wide, and not specific to any one database. @@ -41,10 +41,10 @@ PostgreSQL documentation This utility can only be run by the user who initialized the cluster because it requires read access to the data directory. You can specify the data directory on the command line, or use - the environment variable <envar>PGDATA</>. This utility supports the options - <option>-V</> and <option>--version</>, which print the + the environment variable <envar>PGDATA</envar>. This utility supports the options + <option>-V</option> and <option>--version</option>, which print the <application>pg_controldata</application> version and exit. It also - supports options <option>-?</> and <option>--help</>, which output the + supports options <option>-?</option> and <option>--help</option>, which output the supported arguments. </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index 12fa011c4e5..3bcf0a2e9f0 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -159,13 +159,13 @@ PostgreSQL documentation <para> <option>start</option> mode launches a new server. The server is started in the background, and its standard input is attached - to <filename>/dev/null</filename> (or <literal>nul</> on Windows). + to <filename>/dev/null</filename> (or <literal>nul</literal> on Windows). On Unix-like systems, by default, the server's standard output and standard error are sent to <application>pg_ctl</application>'s standard output (not standard error). The standard output of <application>pg_ctl</application> should then be redirected to a file or piped to another process such as a log rotating program - like <application>rotatelogs</>; otherwise <command>postgres</command> + like <application>rotatelogs</application>; otherwise <command>postgres</command> will write its output to the controlling terminal (from the background) and will not leave the shell's process group. On Windows, by default the server's standard output and standard error @@ -203,7 +203,7 @@ PostgreSQL documentation <para> <option>reload</option> mode simply sends the - <command>postgres</command> server process a <systemitem>SIGHUP</> + <command>postgres</command> server process a <systemitem>SIGHUP</systemitem> signal, causing it to reread its configuration files (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>, etc.). This allows changing @@ -228,14 +228,14 @@ PostgreSQL documentation <para> <option>kill</option> mode sends a signal to a specified process. - This is primarily valuable on <productname>Microsoft Windows</> - which does not have a built-in <application>kill</> command. Use - <literal>--help</> to see a list of supported signal names. + This is primarily valuable on <productname>Microsoft Windows</productname> + which does not have a built-in <application>kill</application> command. Use + <literal>--help</literal> to see a list of supported signal names. </para> <para> - <option>register</option> mode registers the <productname>PostgreSQL</> - server as a system service on <productname>Microsoft Windows</>. + <option>register</option> mode registers the <productname>PostgreSQL</productname> + server as a system service on <productname>Microsoft Windows</productname>. The <option>-S</option> option allows selection of service start type, either <quote>auto</quote> (start service automatically on system startup) or <quote>demand</quote> (start service on demand). @@ -243,7 +243,7 @@ PostgreSQL documentation <para> <option>unregister</option> mode unregisters a system service - on <productname>Microsoft Windows</>. This undoes the effects of the + on <productname>Microsoft Windows</productname>. This undoes the effects of the <option>register</option> command. </para> </refsect1> @@ -286,7 +286,7 @@ PostgreSQL documentation <para> Append the server log output to <replaceable>filename</replaceable>. If the file does not - exist, it is created. The <systemitem>umask</> is set to 077, + exist, it is created. The <systemitem>umask</systemitem> is set to 077, so access to the log file is disallowed to other users by default. </para> </listitem> @@ -313,11 +313,11 @@ PostgreSQL documentation <para> Specifies options to be passed directly to the <command>postgres</command> command. - <option>-o</> can be specified multiple times, with all the given + <option>-o</option> can be specified multiple times, with all the given options being passed through. </para> <para> - The <replaceable>options</> should usually be surrounded by single or + The <replaceable>options</replaceable> should usually be surrounded by single or double quotes to ensure that they are passed through as a group. </para> </listitem> @@ -330,11 +330,11 @@ PostgreSQL documentation <para> Specifies options to be passed directly to the <command>initdb</command> command. - <option>-o</> can be specified multiple times, with all the given + <option>-o</option> can be specified multiple times, with all the given options being passed through. </para> <para> - The <replaceable>options</> should usually be surrounded by single or + The <replaceable>options</replaceable> should usually be surrounded by single or double quotes to ensure that they are passed through as a group. </para> </listitem> @@ -377,15 +377,15 @@ PostgreSQL documentation <para> Specifies the maximum number of seconds to wait when waiting for an operation to complete (see option <option>-w</option>). Defaults to - the value of the <envar>PGCTLTIMEOUT</> environment variable or, if + the value of the <envar>PGCTLTIMEOUT</envar> environment variable or, if not set, to 60 seconds. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_ctl</application> version and exit. @@ -446,8 +446,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_ctl</application> command line @@ -507,7 +507,7 @@ PostgreSQL documentation <term><option>-S <replaceable class="parameter">start-type</replaceable></option></term> <listitem> <para> - Start type of the system service. <replaceable>start-type</> can + Start type of the system service. <replaceable>start-type</replaceable> can be <literal>auto</literal>, or <literal>demand</literal>, or the first letter of one of these two. If this option is omitted, <literal>auto</literal> is the default. @@ -559,14 +559,14 @@ PostgreSQL documentation <para> Most <command>pg_ctl</command> modes require knowing the data directory - location; therefore, the <option>-D</> option is required + location; therefore, the <option>-D</option> option is required unless <envar>PGDATA</envar> is set. </para> <para> - <command>pg_ctl</command>, like most other <productname>PostgreSQL</> + <command>pg_ctl</command>, like most other <productname>PostgreSQL</productname> utilities, - also uses the environment variables supported by <application>libpq</> + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -661,8 +661,8 @@ PostgreSQL documentation </para> <para> - But if <option>-o</> is specified, that replaces any previous options. - To restart using port 5433, disabling <function>fsync</> upon restart: + But if <option>-o</option> is specified, that replaces any previous options. + To restart using port 5433, disabling <function>fsync</function> upon restart: <screen> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput> </screen></para> diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index 7ccbee4855c..79a9ee09830 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -116,8 +116,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-a</></term> - <term><option>--data-only</></term> + <term><option>-a</option></term> + <term><option>--data-only</option></term> <listitem> <para> Dump only the data, not the schema (data definitions). @@ -126,19 +126,19 @@ PostgreSQL documentation <para> This option is similar to, but for historical reasons not identical - to, specifying <option>--section=data</>. + to, specifying <option>--section=data</option>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-b</></term> - <term><option>--blobs</></term> + <term><option>-b</option></term> + <term><option>--blobs</option></term> <listitem> <para> Include large objects in the dump. This is the default behavior - except when <option>--schema</>, <option>--table</>, or - <option>--schema-only</> is specified. The <option>-b</> + except when <option>--schema</option>, <option>--table</option>, or + <option>--schema-only</option> is specified. The <option>-b</option> switch is therefore only useful to add large objects to dumps where a specific schema or table has been requested. Note that blobs are considered data and therefore will be included when @@ -148,17 +148,17 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-B</></term> - <term><option>--no-blobs</></term> + <term><option>-B</option></term> + <term><option>--no-blobs</option></term> <listitem> <para> Exclude large objects in the dump. </para> <para> - When both <option>-b</> and <option>-B</> are given, the behavior + When both <option>-b</option> and <option>-B</option> are given, the behavior is to output large objects, when data is being dumped, see the - <option>-b</> documentation. + <option>-b</option> documentation. </para> </listitem> </varlistentry> @@ -170,7 +170,7 @@ PostgreSQL documentation <para> Output commands to clean (drop) database objects prior to outputting the commands for creating them. - (Unless <option>--if-exists</> is also specified, + (Unless <option>--if-exists</option> is also specified, restore might generate some harmless error messages, if any objects were not present in the destination database.) </para> @@ -184,8 +184,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-C</></term> - <term><option>--create</></term> + <term><option>-C</option></term> + <term><option>--create</option></term> <listitem> <para> Begin the output with a command to create the @@ -242,8 +242,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><literal>p</></term> - <term><literal>plain</></term> + <term><literal>p</literal></term> + <term><literal>plain</literal></term> <listitem> <para> Output a plain-text <acronym>SQL</acronym> script file (the default). @@ -252,8 +252,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><literal>c</></term> - <term><literal>custom</></term> + <term><literal>c</literal></term> + <term><literal>custom</literal></term> <listitem> <para> Output a custom-format archive suitable for input into @@ -267,8 +267,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><literal>d</></term> - <term><literal>directory</></term> + <term><literal>d</literal></term> + <term><literal>directory</literal></term> <listitem> <para> Output a directory-format archive suitable for input into @@ -286,8 +286,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><literal>t</></term> - <term><literal>tar</></term> + <term><literal>t</literal></term> + <term><literal>tar</literal></term> <listitem> <para> Output a <command>tar</command>-format archive suitable for input @@ -305,8 +305,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-j <replaceable class="parameter">njobs</replaceable></></term> - <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></></term> + <term><option>-j <replaceable class="parameter">njobs</replaceable></option></term> + <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term> <listitem> <para> Run the dump in parallel by dumping <replaceable class="parameter">njobs</replaceable> @@ -315,13 +315,13 @@ PostgreSQL documentation directory output format because this is the only output format where multiple processes can write their data at the same time. </para> - <para><application>pg_dump</> will open <replaceable class="parameter">njobs</replaceable> + <para><application>pg_dump</application> will open <replaceable class="parameter">njobs</replaceable> + 1 connections to the database, so make sure your <xref linkend="guc-max-connections"> setting is high enough to accommodate all connections. </para> <para> Requesting exclusive locks on database objects while running a parallel dump could - cause the dump to fail. The reason is that the <application>pg_dump</> master process + cause the dump to fail. The reason is that the <application>pg_dump</application> master process requests shared locks on the objects that the worker processes are going to dump later in order to make sure that nobody deletes them and makes them go away while the dump is running. @@ -330,10 +330,10 @@ PostgreSQL documentation released. Consequently any other access to the table will not be granted either and will queue after the exclusive lock request. This includes the worker process trying to dump the table. Without any precautions this would be a classic deadlock situation. - To detect this conflict, the <application>pg_dump</> worker process requests another - shared lock using the <literal>NOWAIT</> option. If the worker process is not granted + To detect this conflict, the <application>pg_dump</application> worker process requests another + shared lock using the <literal>NOWAIT</literal> option. If the worker process is not granted this shared lock, somebody else must have requested an exclusive lock in the meantime - and there is no way to continue with the dump, so <application>pg_dump</> has no choice + and there is no way to continue with the dump, so <application>pg_dump</application> has no choice but to abort the dump. </para> <para> @@ -371,10 +371,10 @@ PostgreSQL documentation schema itself, and all its contained objects. When this option is not specified, all non-system schemas in the target database will be dumped. Multiple schemas can be - selected by writing multiple <option>-n</> switches. Also, the + selected by writing multiple <option>-n</option> switches. Also, the <replaceable class="parameter">schema</replaceable> parameter is interpreted as a pattern according to the same rules used by - <application>psql</>'s <literal>\d</> commands (see <xref + <application>psql</application>'s <literal>\d</literal> commands (see <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">), so multiple schemas can also be selected by writing wildcard characters in the pattern. When using wildcards, be careful to quote the pattern @@ -384,7 +384,7 @@ PostgreSQL documentation <note> <para> - When <option>-n</> is specified, <application>pg_dump</application> + When <option>-n</option> is specified, <application>pg_dump</application> makes no attempt to dump any other database objects that the selected schema(s) might depend upon. Therefore, there is no guarantee that the results of a specific-schema dump can be successfully @@ -394,9 +394,9 @@ PostgreSQL documentation <note> <para> - Non-schema objects such as blobs are not dumped when <option>-n</> is + Non-schema objects such as blobs are not dumped when <option>-n</option> is specified. You can add blobs back to the dump with the - <option>--blobs</> switch. + <option>--blobs</option> switch. </para> </note> @@ -410,29 +410,29 @@ PostgreSQL documentation <para> Do not dump any schemas matching the <replaceable class="parameter">schema</replaceable> pattern. The pattern is - interpreted according to the same rules as for <option>-n</>. - <option>-N</> can be given more than once to exclude schemas + interpreted according to the same rules as for <option>-n</option>. + <option>-N</option> can be given more than once to exclude schemas matching any of several patterns. </para> <para> - When both <option>-n</> and <option>-N</> are given, the behavior - is to dump just the schemas that match at least one <option>-n</> - switch but no <option>-N</> switches. If <option>-N</> appears - without <option>-n</>, then schemas matching <option>-N</> are + When both <option>-n</option> and <option>-N</option> are given, the behavior + is to dump just the schemas that match at least one <option>-n</option> + switch but no <option>-N</option> switches. If <option>-N</option> appears + without <option>-n</option>, then schemas matching <option>-N</option> are excluded from what is otherwise a normal dump. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-o</></term> - <term><option>--oids</></term> + <term><option>-o</option></term> + <term><option>--oids</option></term> <listitem> <para> Dump object identifiers (<acronym>OID</acronym>s) as part of the data for every table. Use this option if your application references - the <acronym>OID</> + the <acronym>OID</acronym> columns in some way (e.g., in a foreign key constraint). Otherwise, this option should not be used. </para> @@ -440,21 +440,21 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-O</></term> + <term><option>-O</option></term> <term><option>--no-owner</option></term> <listitem> <para> Do not output commands to set ownership of objects to match the original database. By default, <application>pg_dump</application> issues - <command>ALTER OWNER</> or + <command>ALTER OWNER</command> or <command>SET SESSION AUTHORIZATION</command> statements to set ownership of created database objects. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script). To make a script that can be restored by any user, but will give - that user ownership of all the objects, specify <option>-O</>. + that user ownership of all the objects, specify <option>-O</option>. </para> <para> @@ -484,18 +484,18 @@ PostgreSQL documentation Dump only the object definitions (schema), not data. </para> <para> - This option is the inverse of <option>--data-only</>. + This option is the inverse of <option>--data-only</option>. It is similar to, but for historical reasons not identical to, specifying - <option>--section=pre-data --section=post-data</>. + <option>--section=pre-data --section=post-data</option>. </para> <para> - (Do not confuse this with the <option>--schema</> option, which - uses the word <quote>schema</> in a different meaning.) + (Do not confuse this with the <option>--schema</option> option, which + uses the word <quote>schema</quote> in a different meaning.) </para> <para> To exclude table data for only a subset of tables in the database, - see <option>--exclude-table-data</>. + see <option>--exclude-table-data</option>. </para> </listitem> </varlistentry> @@ -506,7 +506,7 @@ PostgreSQL documentation <listitem> <para> Specify the superuser user name to use when disabling triggers. - This is relevant only if <option>--disable-triggers</> is used. + This is relevant only if <option>--disable-triggers</option> is used. (Usually, it's better to leave this out, and instead start the resulting script as superuser.) </para> @@ -520,12 +520,12 @@ PostgreSQL documentation <para> Dump only tables with names matching <replaceable class="parameter">table</replaceable>. - For this purpose, <quote>table</> includes views, materialized views, + For this purpose, <quote>table</quote> includes views, materialized views, sequences, and foreign tables. Multiple tables - can be selected by writing multiple <option>-t</> switches. Also, the + can be selected by writing multiple <option>-t</option> switches. Also, the <replaceable class="parameter">table</replaceable> parameter is interpreted as a pattern according to the same rules used by - <application>psql</>'s <literal>\d</> commands (see <xref + <application>psql</application>'s <literal>\d</literal> commands (see <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">), so multiple tables can also be selected by writing wildcard characters in the pattern. When using wildcards, be careful to quote the pattern @@ -534,15 +534,15 @@ PostgreSQL documentation </para> <para> - The <option>-n</> and <option>-N</> switches have no effect when - <option>-t</> is used, because tables selected by <option>-t</> will + The <option>-n</option> and <option>-N</option> switches have no effect when + <option>-t</option> is used, because tables selected by <option>-t</option> will be dumped regardless of those switches, and non-table objects will not be dumped. </para> <note> <para> - When <option>-t</> is specified, <application>pg_dump</application> + When <option>-t</option> is specified, <application>pg_dump</application> makes no attempt to dump any other database objects that the selected table(s) might depend upon. Therefore, there is no guarantee that the results of a specific-table dump can be successfully @@ -552,14 +552,14 @@ PostgreSQL documentation <note> <para> - The behavior of the <option>-t</> switch is not entirely upward + The behavior of the <option>-t</option> switch is not entirely upward compatible with pre-8.2 <productname>PostgreSQL</productname> - versions. Formerly, writing <literal>-t tab</> would dump all - tables named <literal>tab</>, but now it just dumps whichever one + versions. Formerly, writing <literal>-t tab</literal> would dump all + tables named <literal>tab</literal>, but now it just dumps whichever one is visible in your default search path. To get the old behavior - you can write <literal>-t '*.tab'</>. Also, you must write something - like <literal>-t sch.tab</> to select a table in a particular schema, - rather than the old locution of <literal>-n sch -t tab</>. + you can write <literal>-t '*.tab'</literal>. Also, you must write something + like <literal>-t sch.tab</literal> to select a table in a particular schema, + rather than the old locution of <literal>-n sch -t tab</literal>. </para> </note> </listitem> @@ -572,24 +572,24 @@ PostgreSQL documentation <para> Do not dump any tables matching the <replaceable class="parameter">table</replaceable> pattern. The pattern is - interpreted according to the same rules as for <option>-t</>. - <option>-T</> can be given more than once to exclude tables + interpreted according to the same rules as for <option>-t</option>. + <option>-T</option> can be given more than once to exclude tables matching any of several patterns. </para> <para> - When both <option>-t</> and <option>-T</> are given, the behavior - is to dump just the tables that match at least one <option>-t</> - switch but no <option>-T</> switches. If <option>-T</> appears - without <option>-t</>, then tables matching <option>-T</> are + When both <option>-t</option> and <option>-T</option> are given, the behavior + is to dump just the tables that match at least one <option>-t</option> + switch but no <option>-T</option> switches. If <option>-T</option> appears + without <option>-t</option>, then tables matching <option>-T</option> are excluded from what is otherwise a normal dump. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-v</></term> - <term><option>--verbose</></term> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> <para> Specifies verbose mode. This will cause @@ -601,8 +601,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_dump</application> version and exit. @@ -611,9 +611,9 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-x</></term> - <term><option>--no-privileges</></term> - <term><option>--no-acl</></term> + <term><option>-x</option></term> + <term><option>--no-privileges</option></term> + <term><option>--no-acl</option></term> <listitem> <para> Prevent dumping of access privileges (grant/revoke commands). @@ -632,7 +632,7 @@ PostgreSQL documentation at a moderate level. For plain text output, setting a nonzero compression level causes the entire output file to be compressed, as though it had been - fed through <application>gzip</>; but the default is not to compress. + fed through <application>gzip</application>; but the default is not to compress. The tar archive format currently does not support compression at all. </para> </listitem> @@ -670,7 +670,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--disable-dollar-quoting</></term> + <term><option>--disable-dollar-quoting</option></term> <listitem> <para> This option disables the use of dollar quoting for function bodies, @@ -680,7 +680,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--disable-triggers</></term> + <term><option>--disable-triggers</option></term> <listitem> <para> This option is relevant only when creating a data-only dump. @@ -692,9 +692,9 @@ PostgreSQL documentation </para> <para> - Presently, the commands emitted for <option>--disable-triggers</> + Presently, the commands emitted for <option>--disable-triggers</option> must be done as superuser. So, you should also specify - a superuser name with <option>-S</>, or preferably be careful to + a superuser name with <option>-S</option>, or preferably be careful to start the resulting script as a superuser. </para> @@ -707,7 +707,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--enable-row-security</></term> + <term><option>--enable-row-security</option></term> <listitem> <para> This option is relevant only when dumping the contents of a table @@ -734,14 +734,14 @@ PostgreSQL documentation <para> Do not dump data for any tables matching the <replaceable class="parameter">table</replaceable> pattern. The pattern is - interpreted according to the same rules as for <option>-t</>. - <option>--exclude-table-data</> can be given more than once to + interpreted according to the same rules as for <option>-t</option>. + <option>--exclude-table-data</option> can be given more than once to exclude tables matching any of several patterns. This option is useful when you need the definition of a particular table even though you do not need the data in it. </para> <para> - To exclude data for all tables in the database, see <option>--schema-only</>. + To exclude data for all tables in the database, see <option>--schema-only</option>. </para> </listitem> </varlistentry> @@ -752,7 +752,7 @@ PostgreSQL documentation <para> Use conditional commands (i.e. add an <literal>IF EXISTS</literal> clause) when cleaning database objects. This option is not valid - unless <option>--clean</> is also specified. + unless <option>--clean</option> is also specified. </para> </listitem> </varlistentry> @@ -782,9 +782,9 @@ PostgreSQL documentation <para> Do not wait forever to acquire shared table locks at the beginning of the dump. Instead fail if unable to lock a table within the specified - <replaceable class="parameter">timeout</>. The timeout may be + <replaceable class="parameter">timeout</replaceable>. The timeout may be specified in any of the formats accepted by <command>SET - statement_timeout</>. (Allowed formats vary depending on the server + statement_timeout</command>. (Allowed formats vary depending on the server version you are dumping from, but an integer number of milliseconds is accepted by all versions.) </para> @@ -833,10 +833,10 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--no-synchronized-snapshots</></term> + <term><option>--no-synchronized-snapshots</option></term> <listitem> <para> - This option allows running <command>pg_dump -j</> against a pre-9.2 + This option allows running <command>pg_dump -j</command> against a pre-9.2 server, see the documentation of the <option>-j</option> parameter for more details. </para> @@ -873,25 +873,25 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--quote-all-identifiers</></term> + <term><option>--quote-all-identifiers</option></term> <listitem> <para> Force quoting of all identifiers. This option is recommended when - dumping a database from a server whose <productname>PostgreSQL</> - major version is different from <application>pg_dump</>'s, or when + dumping a database from a server whose <productname>PostgreSQL</productname> + major version is different from <application>pg_dump</application>'s, or when the output is intended to be loaded into a server of a different - major version. By default, <application>pg_dump</> quotes only + major version. By default, <application>pg_dump</application> quotes only identifiers that are reserved words in its own major version. This sometimes results in compatibility issues when dealing with servers of other versions that may have slightly different sets - of reserved words. Using <option>--quote-all-identifiers</> prevents + of reserved words. Using <option>--quote-all-identifiers</option> prevents such issues, at the price of a harder-to-read dump script. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--load-via-partition-root</></term> + <term><option>--load-via-partition-root</option></term> <listitem> <para> When dumping a COPY or INSERT statement for a partitioned table, @@ -910,7 +910,7 @@ PostgreSQL documentation <listitem> <para> Only dump the named section. The section name can be - <option>pre-data</>, <option>data</>, or <option>post-data</>. + <option>pre-data</option>, <option>data</option>, or <option>post-data</option>. This option can be specified more than once to select multiple sections. The default is to dump all sections. </para> @@ -981,7 +981,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--strict-names</></term> + <term><option>--strict-names</option></term> <listitem> <para> Require that each schema @@ -1003,23 +1003,23 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--use-set-session-authorization</></term> + <term><option>--use-set-session-authorization</option></term> <listitem> <para> - Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands - instead of <command>ALTER OWNER</> commands to determine object + Output SQL-standard <command>SET SESSION AUTHORIZATION</command> commands + instead of <command>ALTER OWNER</command> commands to determine object ownership. This makes the dump more standards-compatible, but depending on the history of the objects in the dump, might not restore - properly. Also, a dump using <command>SET SESSION AUTHORIZATION</> + properly. Also, a dump using <command>SET SESSION AUTHORIZATION</command> will certainly require superuser privileges to restore correctly, - whereas <command>ALTER OWNER</> requires lesser privileges. + whereas <command>ALTER OWNER</command> requires lesser privileges. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_dump</application> command line @@ -1036,8 +1036,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-d <replaceable class="parameter">dbname</replaceable></></term> - <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term> + <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to. This is @@ -1093,8 +1093,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -1122,7 +1122,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>pg_dump</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -1133,11 +1133,11 @@ PostgreSQL documentation <listitem> <para> Specifies a role name to be used to create the dump. - This option causes <application>pg_dump</> to issue a - <command>SET ROLE</> <replaceable class="parameter">rolename</> + This option causes <application>pg_dump</application> to issue a + <command>SET ROLE</command> <replaceable class="parameter">rolename</replaceable> command after connecting to the database. It is useful when the - authenticated user (specified by <option>-U</>) lacks privileges - needed by <application>pg_dump</>, but can switch to a role with + authenticated user (specified by <option>-U</option>) lacks privileges + needed by <application>pg_dump</application>, but can switch to a role with the required rights. Some installations have a policy against logging in directly as a superuser, and use of this option allows dumps to be made without violating the policy. @@ -1169,8 +1169,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -1192,7 +1192,7 @@ PostgreSQL documentation <para> The database activity of <application>pg_dump</application> is normally collected by the statistics collector. If this is - undesirable, you can set parameter <varname>track_counts</> + undesirable, you can set parameter <varname>track_counts</varname> to false via <envar>PGOPTIONS</envar> or the <literal>ALTER USER</literal> command. </para> @@ -1204,11 +1204,11 @@ PostgreSQL documentation <title>Notes</title> <para> - If your database cluster has any local additions to the <literal>template1</> database, + If your database cluster has any local additions to the <literal>template1</literal> database, be careful to restore the output of <application>pg_dump</application> into a truly empty database; otherwise you are likely to get errors due to duplicate definitions of the added objects. To make an empty database - without any local additions, copy from <literal>template0</> not <literal>template1</>, + without any local additions, copy from <literal>template0</literal> not <literal>template1</literal>, for example: <programlisting> CREATE DATABASE foo WITH TEMPLATE template0; @@ -1216,7 +1216,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - When a data-only dump is chosen and the option <option>--disable-triggers</> + When a data-only dump is chosen and the option <option>--disable-triggers</option> is used, <application>pg_dump</application> emits commands to disable triggers on user tables before inserting the data, and then commands to re-enable them after the data has been @@ -1232,30 +1232,30 @@ CREATE DATABASE foo WITH TEMPLATE template0; to ensure optimal performance; see <xref linkend="vacuum-for-statistics"> and <xref linkend="autovacuum"> for more information. The dump file also does not - contain any <command>ALTER DATABASE ... SET</> commands; + contain any <command>ALTER DATABASE ... SET</command> commands; these settings are dumped by <xref linkend="app-pg-dumpall">, along with database users and other installation-wide settings. </para> <para> Because <application>pg_dump</application> is used to transfer data - to newer versions of <productname>PostgreSQL</>, the output of + to newer versions of <productname>PostgreSQL</productname>, the output of <application>pg_dump</application> can be expected to load into - <productname>PostgreSQL</> server versions newer than - <application>pg_dump</>'s version. <application>pg_dump</> can also - dump from <productname>PostgreSQL</> servers older than its own version. + <productname>PostgreSQL</productname> server versions newer than + <application>pg_dump</application>'s version. <application>pg_dump</application> can also + dump from <productname>PostgreSQL</productname> servers older than its own version. (Currently, servers back to version 8.0 are supported.) - However, <application>pg_dump</> cannot dump from - <productname>PostgreSQL</> servers newer than its own major version; + However, <application>pg_dump</application> cannot dump from + <productname>PostgreSQL</productname> servers newer than its own major version; it will refuse to even try, rather than risk making an invalid dump. - Also, it is not guaranteed that <application>pg_dump</>'s output can + Also, it is not guaranteed that <application>pg_dump</application>'s output can be loaded into a server of an older major version — not even if the dump was taken from a server of that version. Loading a dump file into an older server may require manual editing of the dump file to remove syntax not understood by the older server. Use of the <option>--quote-all-identifiers</option> option is recommended in cross-version cases, as it can prevent problems arising from varying - reserved-word lists in different <productname>PostgreSQL</> versions. + reserved-word lists in different <productname>PostgreSQL</productname> versions. </para> <para> @@ -1276,7 +1276,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; <title id="pg-dump-examples-title">Examples</title> <para> - To dump a database called <literal>mydb</> into a SQL-script file: + To dump a database called <literal>mydb</literal> into a SQL-script file: <screen> <prompt>$</prompt> <userinput>pg_dump mydb > db.sql</userinput> </screen> @@ -1284,7 +1284,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; <para> To reload such a script into a (freshly created) database named - <literal>newdb</>: + <literal>newdb</literal>: <screen> <prompt>$</prompt> <userinput>psql -d newdb -f db.sql</userinput> @@ -1318,7 +1318,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; <para> To reload an archive file into a (freshly created) database named - <literal>newdb</>: + <literal>newdb</literal>: <screen> <prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput> @@ -1326,7 +1326,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - To dump a single table named <literal>mytab</>: + To dump a single table named <literal>mytab</literal>: <screen> <prompt>$</prompt> <userinput>pg_dump -t mytab mydb > db.sql</userinput> @@ -1334,8 +1334,8 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - To dump all tables whose names start with <literal>emp</> in the - <literal>detroit</> schema, except for the table named + To dump all tables whose names start with <literal>emp</literal> in the + <literal>detroit</literal> schema, except for the table named <literal>employee_log</literal>: <screen> @@ -1344,9 +1344,9 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - To dump all schemas whose names start with <literal>east</> or - <literal>west</> and end in <literal>gsm</>, excluding any schemas whose - names contain the word <literal>test</>: + To dump all schemas whose names start with <literal>east</literal> or + <literal>west</literal> and end in <literal>gsm</literal>, excluding any schemas whose + names contain the word <literal>test</literal>: <screen> <prompt>$</prompt> <userinput>pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql</userinput> @@ -1371,7 +1371,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - To specify an upper-case or mixed-case name in <option>-t</> and related + To specify an upper-case or mixed-case name in <option>-t</option> and related switches, you need to double-quote the name; else it will be folded to lower case (see <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title">). But diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index 1dba702ad95..0a64c3548ef 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -32,7 +32,7 @@ PostgreSQL documentation <para> <application>pg_dumpall</application> is a utility for writing out - (<quote>dumping</quote>) all <productname>PostgreSQL</> databases + (<quote>dumping</quote>) all <productname>PostgreSQL</productname> databases of a cluster into one script file. The script file contains <acronym>SQL</acronym> commands that can be used as input to <xref linkend="app-psql"> to restore the databases. It does this by @@ -63,7 +63,7 @@ PostgreSQL documentation times to the <productname>PostgreSQL</productname> server (once per database). If you use password authentication it will ask for a password each time. It is convenient to have a - <filename>~/.pgpass</> file in such cases. See <xref + <filename>~/.pgpass</filename> file in such cases. See <xref linkend="libpq-pgpass"> for more information. </para> @@ -78,8 +78,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-a</></term> - <term><option>--data-only</></term> + <term><option>-a</option></term> + <term><option>--data-only</option></term> <listitem> <para> Dump only the data, not the schema (data definitions). @@ -93,7 +93,7 @@ PostgreSQL documentation <listitem> <para> Include SQL commands to clean (drop) databases before - recreating them. <command>DROP</> commands for roles and + recreating them. <command>DROP</command> commands for roles and tablespaces are added as well. </para> </listitem> @@ -134,13 +134,13 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-o</></term> - <term><option>--oids</></term> + <term><option>-o</option></term> + <term><option>--oids</option></term> <listitem> <para> Dump object identifiers (<acronym>OID</acronym>s) as part of the data for every table. Use this option if your application references - the <acronym>OID</> + the <acronym>OID</acronym> columns in some way (e.g., in a foreign key constraint). Otherwise, this option should not be used. </para> @@ -148,21 +148,21 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-O</></term> + <term><option>-O</option></term> <term><option>--no-owner</option></term> <listitem> <para> Do not output commands to set ownership of objects to match the original database. By default, <application>pg_dumpall</application> issues - <command>ALTER OWNER</> or + <command>ALTER OWNER</command> or <command>SET SESSION AUTHORIZATION</command> statements to set ownership of created schema elements. These statements will fail when the script is run unless it is started by a superuser (or the same user that owns all of the objects in the script). To make a script that can be restored by any user, but will give - that user ownership of all the objects, specify <option>-O</>. + that user ownership of all the objects, specify <option>-O</option>. </para> </listitem> </varlistentry> @@ -193,7 +193,7 @@ PostgreSQL documentation <listitem> <para> Specify the superuser user name to use when disabling triggers. - This is relevant only if <option>--disable-triggers</> is used. + This is relevant only if <option>--disable-triggers</option> is used. (Usually, it's better to leave this out, and instead start the resulting script as superuser.) </para> @@ -211,21 +211,21 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-v</></term> - <term><option>--verbose</></term> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> <para> Specifies verbose mode. This will cause <application>pg_dumpall</application> to output start/stop times to the dump file, and progress messages to standard error. - It will also enable verbose output in <application>pg_dump</>. + It will also enable verbose output in <application>pg_dump</application>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_dumpall</application> version and exit. @@ -234,9 +234,9 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-x</></term> - <term><option>--no-privileges</></term> - <term><option>--no-acl</></term> + <term><option>-x</option></term> + <term><option>--no-privileges</option></term> + <term><option>--no-acl</option></term> <listitem> <para> Prevent dumping of access privileges (grant/revoke commands). @@ -273,7 +273,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--disable-dollar-quoting</></term> + <term><option>--disable-dollar-quoting</option></term> <listitem> <para> This option disables the use of dollar quoting for function bodies, @@ -283,7 +283,7 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--disable-triggers</></term> + <term><option>--disable-triggers</option></term> <listitem> <para> This option is relevant only when creating a data-only dump. @@ -295,9 +295,9 @@ PostgreSQL documentation </para> <para> - Presently, the commands emitted for <option>--disable-triggers</> + Presently, the commands emitted for <option>--disable-triggers</option> must be done as superuser. So, you should also specify - a superuser name with <option>-S</>, or preferably be careful to + a superuser name with <option>-S</option>, or preferably be careful to start the resulting script as a superuser. </para> </listitem> @@ -309,7 +309,7 @@ PostgreSQL documentation <para> Use conditional commands (i.e. add an <literal>IF EXISTS</literal> clause) to clean databases and other objects. This option is not valid - unless <option>--clean</> is also specified. + unless <option>--clean</option> is also specified. </para> </listitem> </varlistentry> @@ -335,9 +335,9 @@ PostgreSQL documentation <para> Do not wait forever to acquire shared table locks at the beginning of the dump. Instead, fail if unable to lock a table within the specified - <replaceable class="parameter">timeout</>. The timeout may be + <replaceable class="parameter">timeout</replaceable>. The timeout may be specified in any of the formats accepted by <command>SET - statement_timeout</>. Allowed values vary depending on the server + statement_timeout</command>. Allowed values vary depending on the server version you are dumping from, but an integer number of milliseconds is accepted by all versions since 7.3. This option is ignored when dumping from a pre-7.3 server. @@ -426,25 +426,25 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--quote-all-identifiers</></term> + <term><option>--quote-all-identifiers</option></term> <listitem> <para> Force quoting of all identifiers. This option is recommended when - dumping a database from a server whose <productname>PostgreSQL</> - major version is different from <application>pg_dumpall</>'s, or when + dumping a database from a server whose <productname>PostgreSQL</productname> + major version is different from <application>pg_dumpall</application>'s, or when the output is intended to be loaded into a server of a different - major version. By default, <application>pg_dumpall</> quotes only + major version. By default, <application>pg_dumpall</application> quotes only identifiers that are reserved words in its own major version. This sometimes results in compatibility issues when dealing with servers of other versions that may have slightly different sets - of reserved words. Using <option>--quote-all-identifiers</> prevents + of reserved words. Using <option>--quote-all-identifiers</option> prevents such issues, at the price of a harder-to-read dump script. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--load-via-partition-root</></term> + <term><option>--load-via-partition-root</option></term> <listitem> <para> When dumping a COPY or INSERT statement for a partitioned table, @@ -459,11 +459,11 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>--use-set-session-authorization</></term> + <term><option>--use-set-session-authorization</option></term> <listitem> <para> - Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands - instead of <command>ALTER OWNER</> commands to determine object + Output SQL-standard <command>SET SESSION AUTHORIZATION</command> commands + instead of <command>ALTER OWNER</command> commands to determine object ownership. This makes the dump more standards compatible, but depending on the history of the objects in the dump, might not restore properly. @@ -472,8 +472,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_dumpall</application> command line @@ -498,7 +498,7 @@ PostgreSQL documentation string. See <xref linkend="libpq-connstring"> for more information. </para> <para> - The option is called <literal>--dbname</> for consistency with other + The option is called <literal>--dbname</literal> for consistency with other client applications, but because <application>pg_dumpall</application> needs to connect to many databases, database name in the connection string will be ignored. Use <literal>-l</literal> option to specify @@ -559,8 +559,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -588,14 +588,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>pg_dumpall</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> <para> Note that the password prompt will occur again for each database to be dumped. Usually, it's better to set up a - <filename>~/.pgpass</> file than to rely on manual password entry. + <filename>~/.pgpass</filename> file than to rely on manual password entry. </para> </listitem> </varlistentry> @@ -605,11 +605,11 @@ PostgreSQL documentation <listitem> <para> Specifies a role name to be used to create the dump. - This option causes <application>pg_dumpall</> to issue a - <command>SET ROLE</> <replaceable class="parameter">rolename</> + This option causes <application>pg_dumpall</application> to issue a + <command>SET ROLE</command> <replaceable class="parameter">rolename</replaceable> command after connecting to the database. It is useful when the - authenticated user (specified by <option>-U</>) lacks privileges - needed by <application>pg_dumpall</>, but can switch to a role with + authenticated user (specified by <option>-U</option>) lacks privileges + needed by <application>pg_dumpall</application>, but can switch to a role with the required rights. Some installations have a policy against logging in directly as a superuser, and use of this option allows dumps to be made without violating the policy. @@ -640,8 +640,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -658,9 +658,9 @@ PostgreSQL documentation </para> <para> - Once restored, it is wise to run <command>ANALYZE</> on each + Once restored, it is wise to run <command>ANALYZE</command> on each database so the optimizer has useful statistics. You - can also run <command>vacuumdb -a -z</> to analyze all + can also run <command>vacuumdb -a -z</command> to analyze all databases. </para> diff --git a/doc/src/sgml/ref/pg_isready.sgml b/doc/src/sgml/ref/pg_isready.sgml index 2ee79a0bbeb..f140c820792 100644 --- a/doc/src/sgml/ref/pg_isready.sgml +++ b/doc/src/sgml/ref/pg_isready.sgml @@ -43,8 +43,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-d <replaceable class="parameter">dbname</replaceable></></term> - <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term> + <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to. @@ -61,8 +61,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-h <replaceable class="parameter">hostname</replaceable></></term> - <term><option>--host=<replaceable class="parameter">hostname</replaceable></></term> + <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -74,8 +74,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or the local Unix-domain @@ -98,8 +98,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-t <replaceable class="parameter">seconds</replaceable></></term> - <term><option>--timeout=<replaceable class="parameter">seconds</replaceable></></term> + <term><option>-t <replaceable class="parameter">seconds</replaceable></option></term> + <term><option>--timeout=<replaceable class="parameter">seconds</replaceable></option></term> <listitem> <para> The maximum number of seconds to wait when attempting connection before @@ -110,8 +110,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> Connect to the database as the user <replaceable @@ -121,8 +121,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_isready</application> version and exit. @@ -131,8 +131,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_isready</application> command line @@ -159,9 +159,9 @@ PostgreSQL documentation <title>Environment</title> <para> - <command>pg_isready</command>, like most other <productname>PostgreSQL</> + <command>pg_isready</command>, like most other <productname>PostgreSQL</productname> utilities, - also uses the environment variables supported by <application>libpq</> + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_receivewal.sgml b/doc/src/sgml/ref/pg_receivewal.sgml index f0513dad2ae..5395fde6d6a 100644 --- a/doc/src/sgml/ref/pg_receivewal.sgml +++ b/doc/src/sgml/ref/pg_receivewal.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <cmdsynopsis> <command>pg_receivewal</command> - <arg rep="repeat"><replaceable>option</></arg> + <arg rep="repeat"><replaceable>option</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -49,9 +49,9 @@ PostgreSQL documentation </para> <para> - Unlike the WAL receiver of a PostgreSQL standby server, <application>pg_receivewal</> + Unlike the WAL receiver of a PostgreSQL standby server, <application>pg_receivewal</application> by default flushes WAL data only when a WAL file is closed. - The option <option>--synchronous</> must be specified to flush WAL data + The option <option>--synchronous</option> must be specified to flush WAL data in real time. </para> @@ -77,7 +77,7 @@ PostgreSQL documentation <para> In the absence of fatal errors, <application>pg_receivewal</application> will run until terminated by the <systemitem>SIGINT</systemitem> signal - (<keycombo action="simul"><keycap>Control</><keycap>C</></>). + (<keycombo action="simul"><keycap>Control</keycap><keycap>C</keycap></keycombo>). </para> </refsect1> @@ -108,7 +108,7 @@ PostgreSQL documentation </para> <para> - If there is a record with LSN exactly equal to <replaceable>lsn</>, + If there is a record with LSN exactly equal to <replaceable>lsn</replaceable>, the record will be processed. </para> </listitem> @@ -156,7 +156,7 @@ PostgreSQL documentation <para> Require <application>pg_receivewal</application> to use an existing replication slot (see <xref linkend="streaming-replication-slots">). - When this option is used, <application>pg_receivewal</> will report + When this option is used, <application>pg_receivewal</application> will report a flush position to the server, indicating when each segment has been synchronized to disk so that the server can remove that segment if it is not otherwise needed. @@ -181,7 +181,7 @@ PostgreSQL documentation <para> Flush the WAL data to disk immediately after it has been received. Also send a status packet back to the server immediately after flushing, - regardless of <literal>--status-interval</>. + regardless of <literal>--status-interval</literal>. </para> <para> @@ -230,7 +230,7 @@ PostgreSQL documentation string. See <xref linkend="libpq-connstring"> for more information. </para> <para> - The option is called <literal>--dbname</> for consistency with other + The option is called <literal>--dbname</literal> for consistency with other client applications, but because <application>pg_receivewal</application> doesn't connect to any particular database in the cluster, database name in the connection string will be ignored. @@ -276,8 +276,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -305,7 +305,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>pg_receivewal</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -345,8 +345,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_receivewal</application> version and exit. @@ -355,8 +355,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_receivewal</application> command line @@ -386,8 +386,8 @@ PostgreSQL documentation <title>Environment</title> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml index 9c7bb1907be..5add6113f3b 100644 --- a/doc/src/sgml/ref/pg_recvlogical.sgml +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -40,11 +40,11 @@ PostgreSQL documentation </para> <para> - <command>pg_recvlogical</> has no equivalent to the logical decoding + <command>pg_recvlogical</command> has no equivalent to the logical decoding SQL interface's peek and get modes. It sends replay confirmations for data lazily as it receives it and on clean exit. To examine pending data on a slot without consuming it, use - <link linkend="functions-replication"><function>pg_logical_slot_peek_changes</></>. + <link linkend="functions-replication"><function>pg_logical_slot_peek_changes</function></link>. </para> </refsect1> @@ -125,7 +125,7 @@ PostgreSQL documentation </para> <para> - If there's a record with LSN exactly equal to <replaceable>lsn</>, + If there's a record with LSN exactly equal to <replaceable>lsn</replaceable>, the record will be output. </para> @@ -145,7 +145,7 @@ PostgreSQL documentation <listitem> <para> Write received and decoded transaction data into this - file. Use <literal>-</> for <systemitem>stdout</systemitem>. + file. Use <literal>-</literal> for <systemitem>stdout</systemitem>. </para> </listitem> </varlistentry> @@ -257,8 +257,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-v</></term> - <term><option>--verbose</></term> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> <para> Enables verbose mode. @@ -353,7 +353,7 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>pg_recvlogical</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -366,8 +366,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_recvlogical</application> version and exit. @@ -376,8 +376,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_recvlogical</application> command line @@ -393,8 +393,8 @@ PostgreSQL documentation <title>Environment</title> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> </refsect1> diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml index defaf170dc6..c8e5790a8e7 100644 --- a/doc/src/sgml/ref/pg_resetwal.sgml +++ b/doc/src/sgml/ref/pg_resetwal.sgml @@ -34,7 +34,7 @@ PostgreSQL documentation <para> <command>pg_resetwal</command> clears the write-ahead log (WAL) and optionally resets some other control information stored in the - <filename>pg_control</> file. This function is sometimes needed + <filename>pg_control</filename> file. This function is sometimes needed if these files have become corrupted. It should be used only as a last resort, when the server will not start due to such corruption. </para> @@ -43,7 +43,7 @@ PostgreSQL documentation After running this command, it should be possible to start the server, but bear in mind that the database might contain inconsistent data due to partially-committed transactions. You should immediately dump your data, - run <command>initdb</>, and reload. After reload, check for + run <command>initdb</command>, and reload. After reload, check for inconsistencies and repair as needed. </para> @@ -52,21 +52,21 @@ PostgreSQL documentation it requires read/write access to the data directory. For safety reasons, you must specify the data directory on the command line. <command>pg_resetwal</command> does not use the environment variable - <envar>PGDATA</>. + <envar>PGDATA</envar>. </para> <para> If <command>pg_resetwal</command> complains that it cannot determine - valid data for <filename>pg_control</>, you can force it to proceed anyway - by specifying the <option>-f</> (force) option. In this case plausible + valid data for <filename>pg_control</filename>, you can force it to proceed anyway + by specifying the <option>-f</option> (force) option. In this case plausible values will be substituted for the missing data. Most of the fields can be expected to match, but manual assistance might be needed for the next OID, next transaction ID and epoch, next multitransaction ID and offset, and WAL starting address fields. These fields can be set using the options discussed below. If you are not able to determine correct values for all - these fields, <option>-f</> can still be used, but + these fields, <option>-f</option> can still be used, but the recovered database must be treated with even more suspicion than - usual: an immediate dump and reload is imperative. <emphasis>Do not</> + usual: an immediate dump and reload is imperative. <emphasis>Do not</emphasis> execute any data-modifying operations in the database before you dump, as any such action is likely to make the corruption worse. </para> @@ -81,7 +81,7 @@ PostgreSQL documentation <listitem> <para> Force <command>pg_resetwal</command> to proceed even if it cannot determine - valid data for <filename>pg_control</>, as explained above. + valid data for <filename>pg_control</filename>, as explained above. </para> </listitem> </varlistentry> @@ -90,9 +90,9 @@ PostgreSQL documentation <term><option>-n</option></term> <listitem> <para> - The <option>-n</> (no operation) option instructs + The <option>-n</option> (no operation) option instructs <command>pg_resetwal</command> to print the values reconstructed from - <filename>pg_control</> and values about to be changed, and then exit + <filename>pg_control</filename> and values about to be changed, and then exit without modifying anything. This is mainly a debugging tool, but can be useful as a sanity check before allowing <command>pg_resetwal</command> to proceed for real. @@ -116,7 +116,7 @@ PostgreSQL documentation <para> The following options are only needed when <command>pg_resetwal</command> is unable to determine appropriate values - by reading <filename>pg_control</>. Safe values can be determined as + by reading <filename>pg_control</filename>. Safe values can be determined as described below. For values that take numeric arguments, hexadecimal values can be specified by using the prefix <literal>0x</literal>. </para> @@ -134,7 +134,7 @@ PostgreSQL documentation A safe value for the oldest transaction ID for which the commit time can be retrieved (first part) can be determined by looking for the numerically smallest file name in the directory - <filename>pg_commit_ts</> under the data directory. Conversely, a safe + <filename>pg_commit_ts</filename> under the data directory. Conversely, a safe value for the newest transaction ID for which the commit time can be retrieved (second part) can be determined by looking for the numerically greatest file name in the same directory. The file names are in @@ -155,8 +155,8 @@ PostgreSQL documentation except in the field that is set by <command>pg_resetwal</command>, so any value will work so far as the database itself is concerned. You might need to adjust this value to ensure that replication - systems such as <application>Slony-I</> and - <application>Skytools</> work correctly — + systems such as <application>Slony-I</application> and + <application>Skytools</application> work correctly — if so, an appropriate value should be obtainable from the state of the downstream replicated database. </para> @@ -173,22 +173,22 @@ PostgreSQL documentation <para> The WAL starting address should be larger than any WAL segment file name currently existing in - the directory <filename>pg_wal</> under the data directory. + the directory <filename>pg_wal</filename> under the data directory. These names are also in hexadecimal and have three parts. The first - part is the <quote>timeline ID</> and should usually be kept the same. - For example, if <filename>00000001000000320000004A</> is the - largest entry in <filename>pg_wal</>, use <literal>-l 00000001000000320000004B</> or higher. + part is the <quote>timeline ID</quote> and should usually be kept the same. + For example, if <filename>00000001000000320000004A</filename> is the + largest entry in <filename>pg_wal</filename>, use <literal>-l 00000001000000320000004B</literal> or higher. </para> <note> <para> <command>pg_resetwal</command> itself looks at the files in - <filename>pg_wal</> and chooses a default <option>-l</> setting + <filename>pg_wal</filename> and chooses a default <option>-l</option> setting beyond the last existing file name. Therefore, manual adjustment of - <option>-l</> should only be needed if you are aware of WAL segment - files that are not currently present in <filename>pg_wal</>, such as + <option>-l</option> should only be needed if you are aware of WAL segment + files that are not currently present in <filename>pg_wal</filename>, such as entries in an offline archive; or if the contents of - <filename>pg_wal</> have been lost entirely. + <filename>pg_wal</filename> have been lost entirely. </para> </note> </listitem> @@ -204,10 +204,10 @@ PostgreSQL documentation <para> A safe value for the next multitransaction ID (first part) can be determined by looking for the numerically largest file name in the - directory <filename>pg_multixact/offsets</> under the data directory, + directory <filename>pg_multixact/offsets</filename> under the data directory, adding one, and then multiplying by 65536 (0x10000). Conversely, a safe value for the oldest multitransaction ID (second part of - <option>-m</>) can be determined by looking for the numerically smallest + <option>-m</option>) can be determined by looking for the numerically smallest file name in the same directory and multiplying by 65536. The file names are in hexadecimal, so the easiest way to do this is to specify the option value in hexadecimal and append four zeroes. @@ -239,7 +239,7 @@ PostgreSQL documentation <para> A safe value can be determined by looking for the numerically largest - file name in the directory <filename>pg_multixact/members</> under the + file name in the directory <filename>pg_multixact/members</filename> under the data directory, adding one, and then multiplying by 52352 (0xCC80). The file names are in hexadecimal. There is no simple recipe such as the ones for other options of appending zeroes. @@ -256,12 +256,12 @@ PostgreSQL documentation <para> A safe value can be determined by looking for the numerically largest - file name in the directory <filename>pg_xact</> under the data directory, + file name in the directory <filename>pg_xact</filename> under the data directory, adding one, and then multiplying by 1048576 (0x100000). Note that the file names are in hexadecimal. It is usually easiest to specify the option value in - hexadecimal too. For example, if <filename>0011</> is the largest entry - in <filename>pg_xact</>, <literal>-x 0x1200000</> will work (five + hexadecimal too. For example, if <filename>0011</filename> is the largest entry + in <filename>pg_xact</filename>, <literal>-x 0x1200000</literal> will work (five trailing zeroes provide the proper multiplier). </para> </listitem> diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index a628e793109..ed535f6f89a 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -98,7 +98,7 @@ <para> This option is similar to, but for historical reasons not identical - to, specifying <option>--section=data</>. + to, specifying <option>--section=data</option>. </para> </listitem> </varlistentry> @@ -109,7 +109,7 @@ <listitem> <para> Clean (drop) database objects before recreating them. - (Unless <option>--if-exists</> is used, + (Unless <option>--if-exists</option> is used, this might generate some harmless error messages, if any objects were not present in the destination database.) </para> @@ -128,8 +128,8 @@ <para> When this option is used, the database named with <option>-d</option> - is used only to issue the initial <command>DROP DATABASE</> and - <command>CREATE DATABASE</> commands. All data is restored into the + is used only to issue the initial <command>DROP DATABASE</command> and + <command>CREATE DATABASE</command> commands. All data is restored into the database name that appears in the archive. </para> </listitem> @@ -183,8 +183,8 @@ <variablelist> <varlistentry> - <term><literal>c</></term> - <term><literal>custom</></term> + <term><literal>c</literal></term> + <term><literal>custom</literal></term> <listitem> <para> The archive is in the custom format of @@ -194,8 +194,8 @@ </varlistentry> <varlistentry> - <term><literal>d</></term> - <term><literal>directory</></term> + <term><literal>d</literal></term> + <term><literal>directory</literal></term> <listitem> <para> The archive is a directory archive. @@ -204,8 +204,8 @@ </varlistentry> <varlistentry> - <term><literal>t</></term> - <term><literal>tar</></term> + <term><literal>t</literal></term> + <term><literal>tar</literal></term> <listitem> <para> The archive is a <command>tar</command> archive. @@ -222,7 +222,7 @@ <listitem> <para> Restore definition of named index only. Multiple indexes - may be specified with multiple <option>-I</> switches. + may be specified with multiple <option>-I</option> switches. </para> </listitem> </varlistentry> @@ -233,7 +233,7 @@ <listitem> <para> Run the most time-consuming parts - of <application>pg_restore</> — those which load data, + of <application>pg_restore</application> — those which load data, create indexes, or create constraints — using multiple concurrent jobs. This option can dramatically reduce the time to restore a large database to a server running on a @@ -275,8 +275,8 @@ <para> List the table of contents of the archive. The output of this operation can be used as input to the <option>-L</option> option. Note that - if filtering switches such as <option>-n</> or <option>-t</> are - used with <option>-l</>, they will restrict the items listed. + if filtering switches such as <option>-n</option> or <option>-t</option> are + used with <option>-l</option>, they will restrict the items listed. </para> </listitem> </varlistentry> @@ -289,11 +289,11 @@ Restore only those archive elements that are listed in <replaceable class="parameter">list-file</replaceable>, and restore them in the order they appear in the file. Note that - if filtering switches such as <option>-n</> or <option>-t</> are - used with <option>-L</>, they will further restrict the items restored. + if filtering switches such as <option>-n</option> or <option>-t</option> are + used with <option>-L</option>, they will further restrict the items restored. </para> - <para><replaceable class="parameter">list-file</> is normally created by - editing the output of a previous <option>-l</> operation. + <para><replaceable class="parameter">list-file</replaceable> is normally created by + editing the output of a previous <option>-l</option> operation. Lines can be moved or removed, and can also be commented out by placing a semicolon (<literal>;</literal>) at the start of the line. See below for examples. @@ -307,7 +307,7 @@ <listitem> <para> Restore only objects that are in the named schema. Multiple schemas - may be specified with multiple <option>-n</> switches. This can be + may be specified with multiple <option>-n</option> switches. This can be combined with the <option>-t</option> option to restore just a specific table. </para> @@ -320,12 +320,12 @@ <listitem> <para> Do not restore objects that are in the named schema. Multiple schemas - to be excluded may be specified with multiple <option>-N</> switches. + to be excluded may be specified with multiple <option>-N</option> switches. </para> <para> - When both <option>-n</> and <option>-N</> are given for the same - schema name, the <option>-N</> switch wins and the schema is excluded. + When both <option>-n</option> and <option>-N</option> are given for the same + schema name, the <option>-N</option> switch wins and the schema is excluded. </para> </listitem> </varlistentry> @@ -338,7 +338,7 @@ Do not output commands to set ownership of objects to match the original database. By default, <application>pg_restore</application> issues - <command>ALTER OWNER</> or + <command>ALTER OWNER</command> or <command>SET SESSION AUTHORIZATION</command> statements to set ownership of created schema elements. These statements will fail unless the initial connection to the @@ -358,7 +358,7 @@ Restore the named function only. Be careful to spell the function name and arguments exactly as they appear in the dump file's table of contents. Multiple functions may be specified with multiple - <option>-P</> switches. + <option>-P</option> switches. </para> </listitem> </varlistentry> @@ -383,14 +383,14 @@ to the extent that schema entries are present in the archive. </para> <para> - This option is the inverse of <option>--data-only</>. + This option is the inverse of <option>--data-only</option>. It is similar to, but for historical reasons not identical to, specifying - <option>--section=pre-data --section=post-data</>. + <option>--section=pre-data --section=post-data</option>. </para> <para> - (Do not confuse this with the <option>--schema</> option, which - uses the word <quote>schema</> in a different meaning.) + (Do not confuse this with the <option>--schema</option> option, which + uses the word <quote>schema</quote> in a different meaning.) </para> </listitem> </varlistentry> @@ -401,7 +401,7 @@ <listitem> <para> Specify the superuser user name to use when disabling triggers. - This is relevant only if <option>--disable-triggers</> is used. + This is relevant only if <option>--disable-triggers</option> is used. </para> </listitem> </varlistentry> @@ -412,16 +412,16 @@ <listitem> <para> Restore definition and/or data of only the named table. - For this purpose, <quote>table</> includes views, materialized views, + For this purpose, <quote>table</quote> includes views, materialized views, sequences, and foreign tables. Multiple tables - can be selected by writing multiple <option>-t</> switches. + can be selected by writing multiple <option>-t</option> switches. This option can be combined with the <option>-n</option> option to specify table(s) in a particular schema. </para> <note> <para> - When <option>-t</option> is specified, <application>pg_restore</> + When <option>-t</option> is specified, <application>pg_restore</application> makes no attempt to restore any other database objects that the selected table(s) might depend upon. Therefore, there is no guarantee that a specific-table restore into a clean database will @@ -433,14 +433,14 @@ <para> This flag does not behave identically to the <option>-t</option> flag of <application>pg_dump</application>. There is not currently - any provision for wild-card matching in <application>pg_restore</>, - nor can you include a schema name within its <option>-t</>. + any provision for wild-card matching in <application>pg_restore</application>, + nor can you include a schema name within its <option>-t</option>. </para> </note> <note> <para> - In versions prior to <productname>PostgreSQL</> 9.6, this flag + In versions prior to <productname>PostgreSQL</productname> 9.6, this flag matched only tables, not any other type of relation. </para> </note> @@ -453,7 +453,7 @@ <listitem> <para> Restore named trigger only. Multiple triggers may be specified with - multiple <option>-T</> switches. + multiple <option>-T</option> switches. </para> </listitem> </varlistentry> @@ -469,8 +469,8 @@ </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_restore</application> version and exit. @@ -495,16 +495,16 @@ <listitem> <para> Execute the restore as a single transaction (that is, wrap the - emitted commands in <command>BEGIN</>/<command>COMMIT</>). This + emitted commands in <command>BEGIN</command>/<command>COMMIT</command>). This ensures that either all the commands complete successfully, or no changes are applied. This option implies - <option>--exit-on-error</>. + <option>--exit-on-error</option>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--disable-triggers</></term> + <term><option>--disable-triggers</option></term> <listitem> <para> This option is relevant only when performing a data-only restore. @@ -517,16 +517,16 @@ <para> Presently, the commands emitted for - <option>--disable-triggers</> must be done as superuser. So you - should also specify a superuser name with <option>-S</> or, + <option>--disable-triggers</option> must be done as superuser. So you + should also specify a superuser name with <option>-S</option> or, preferably, run <application>pg_restore</application> as a - <productname>PostgreSQL</> superuser. + <productname>PostgreSQL</productname> superuser. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--enable-row-security</></term> + <term><option>--enable-row-security</option></term> <listitem> <para> This option is relevant only when restoring the contents of a table @@ -554,7 +554,7 @@ <para> Use conditional commands (i.e. add an <literal>IF EXISTS</literal> clause) when cleaning database objects. This option is not valid - unless <option>--clean</> is also specified. + unless <option>--clean</option> is also specified. </para> </listitem> </varlistentry> @@ -568,8 +568,8 @@ With this option, data for such a table is skipped. This behavior is useful if the target database already contains the desired table contents. For example, - auxiliary tables for <productname>PostgreSQL</> extensions - such as <productname>PostGIS</> might already be loaded in + auxiliary tables for <productname>PostgreSQL</productname> extensions + such as <productname>PostGIS</productname> might already be loaded in the target database; specifying this option prevents duplicate or obsolete data from being loaded into them. </para> @@ -627,7 +627,7 @@ <listitem> <para> Only restore the named section. The section name can be - <option>pre-data</>, <option>data</>, or <option>post-data</>. + <option>pre-data</option>, <option>data</option>, or <option>post-data</option>. This option can be specified more than once to select multiple sections. The default is to restore all sections. </para> @@ -642,7 +642,7 @@ </varlistentry> <varlistentry> - <term><option>--strict-names</></term> + <term><option>--strict-names</option></term> <listitem> <para> Require that each schema @@ -657,8 +657,8 @@ <term><option>--use-set-session-authorization</option></term> <listitem> <para> - Output SQL-standard <command>SET SESSION AUTHORIZATION</> commands - instead of <command>ALTER OWNER</> commands to determine object + Output SQL-standard <command>SET SESSION AUTHORIZATION</command> commands + instead of <command>ALTER OWNER</command> commands to determine object ownership. This makes the dump more standards-compatible, but depending on the history of the objects in the dump, might not restore properly. @@ -667,8 +667,8 @@ </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_restore</application> command line @@ -723,8 +723,8 @@ </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -752,7 +752,7 @@ for a password if the server demands password authentication. However, <application>pg_restore</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> @@ -763,11 +763,11 @@ <listitem> <para> Specifies a role name to be used to perform the restore. - This option causes <application>pg_restore</> to issue a - <command>SET ROLE</> <replaceable class="parameter">rolename</> + This option causes <application>pg_restore</application> to issue a + <command>SET ROLE</command> <replaceable class="parameter">rolename</replaceable> command after connecting to the database. It is useful when the - authenticated user (specified by <option>-U</>) lacks privileges - needed by <application>pg_restore</>, but can switch to a role with + authenticated user (specified by <option>-U</option>) lacks privileges + needed by <application>pg_restore</application>, but can switch to a role with the required rights. Some installations have a policy against logging in directly as a superuser, and use of this option allows restores to be performed without violating the policy. @@ -799,8 +799,8 @@ </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). However, it does not read <envar>PGDATABASE</envar> when a database name is not supplied. </para> @@ -829,11 +829,11 @@ <para> If your installation has any local additions to the - <literal>template1</> database, be careful to load the output of + <literal>template1</literal> database, be careful to load the output of <application>pg_restore</application> into a truly empty database; otherwise you are likely to get errors due to duplicate definitions of the added objects. To make an empty database without any local - additions, copy from <literal>template0</> not <literal>template1</>, for example: + additions, copy from <literal>template0</literal> not <literal>template1</literal>, for example: <programlisting> CREATE DATABASE foo WITH TEMPLATE template0; </programlisting> @@ -846,7 +846,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; <listitem> <para> When restoring data to a pre-existing table and the option - <option>--disable-triggers</> is used, + <option>--disable-triggers</option> is used, <application>pg_restore</application> emits commands to disable triggers on user tables before inserting the data, then emits commands to re-enable them after the data has been inserted. If the restore is stopped in the @@ -872,7 +872,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; </para> <para> - Once restored, it is wise to run <command>ANALYZE</> on each + Once restored, it is wise to run <command>ANALYZE</command> on each restored table so the optimizer has useful statistics; see <xref linkend="vacuum-for-statistics"> and <xref linkend="autovacuum"> for more information. @@ -885,7 +885,7 @@ CREATE DATABASE foo WITH TEMPLATE template0; <title>Examples</title> <para> - Assume we have dumped a database called <literal>mydb</> into a + Assume we have dumped a database called <literal>mydb</literal> into a custom-format dump file: <screen> @@ -901,24 +901,24 @@ CREATE DATABASE foo WITH TEMPLATE template0; <prompt>$</prompt> <userinput>pg_restore -C -d postgres db.dump</userinput> </screen> - The database named in the <option>-d</> switch can be any database existing - in the cluster; <application>pg_restore</> only uses it to issue the - <command>CREATE DATABASE</> command for <literal>mydb</>. With - <option>-C</>, data is always restored into the database name that appears + The database named in the <option>-d</option> switch can be any database existing + in the cluster; <application>pg_restore</application> only uses it to issue the + <command>CREATE DATABASE</command> command for <literal>mydb</literal>. With + <option>-C</option>, data is always restored into the database name that appears in the dump file. </para> <para> - To reload the dump into a new database called <literal>newdb</>: + To reload the dump into a new database called <literal>newdb</literal>: <screen> <prompt>$</prompt> <userinput>createdb -T template0 newdb</userinput> <prompt>$</prompt> <userinput>pg_restore -d newdb db.dump</userinput> </screen> - Notice we don't use <option>-C</>, and instead connect directly to the + Notice we don't use <option>-C</option>, and instead connect directly to the database to be restored into. Also note that we clone the new database - from <literal>template0</> not <literal>template1</>, to ensure it is + from <literal>template0</literal> not <literal>template1</literal>, to ensure it is initially empty. </para> diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index d5430d43245..4bafdfe581c 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -41,7 +41,7 @@ PostgreSQL documentation <title>Description</title> <para> - <application>pg_rewind</> is a tool for synchronizing a PostgreSQL cluster + <application>pg_rewind</application> is a tool for synchronizing a PostgreSQL cluster with another copy of the same cluster, after the clusters' timelines have diverged. A typical scenario is to bring an old master server back online after failover as a standby that follows the new master. @@ -51,49 +51,49 @@ PostgreSQL documentation The result is equivalent to replacing the target data directory with the source one. Only changed blocks from relation files are copied; all other files are copied in full, including configuration files. The - advantage of <application>pg_rewind</> over taking a new base backup, or - tools like <application>rsync</>, is that <application>pg_rewind</> does + advantage of <application>pg_rewind</application> over taking a new base backup, or + tools like <application>rsync</application>, is that <application>pg_rewind</application> does not require reading through unchanged blocks in the cluster. This makes it a lot faster when the database is large and only a small fraction of blocks differ between the clusters. </para> <para> - <application>pg_rewind</> examines the timeline histories of the source + <application>pg_rewind</application> examines the timeline histories of the source and target clusters to determine the point where they diverged, and - expects to find WAL in the target cluster's <filename>pg_wal</> directory + expects to find WAL in the target cluster's <filename>pg_wal</filename> directory reaching all the way back to the point of divergence. The point of divergence can be found either on the target timeline, the source timeline, or their common ancestor. In the typical failover scenario where the target cluster was shut down soon after the divergence, this is not a problem, but if the target cluster ran for a long time after the divergence, the old WAL files might no longer be present. In that case, they can be manually - copied from the WAL archive to the <filename>pg_wal</> directory, or - fetched on startup by configuring <filename>recovery.conf</>. The use of - <application>pg_rewind</> is not limited to failover, e.g. a standby + copied from the WAL archive to the <filename>pg_wal</filename> directory, or + fetched on startup by configuring <filename>recovery.conf</filename>. The use of + <application>pg_rewind</application> is not limited to failover, e.g. a standby server can be promoted, run some write transactions, and then rewinded to become a standby again. </para> <para> When the target server is started for the first time after running - <application>pg_rewind</>, it will go into recovery mode and replay all + <application>pg_rewind</application>, it will go into recovery mode and replay all WAL generated in the source server after the point of divergence. If some of the WAL was no longer available in the source server when - <application>pg_rewind</> was run, and therefore could not be copied by the - <application>pg_rewind</> session, it must be made available when the + <application>pg_rewind</application> was run, and therefore could not be copied by the + <application>pg_rewind</application> session, it must be made available when the target server is started. This can be done by creating a - <filename>recovery.conf</> file in the target data directory with a - suitable <varname>restore_command</>. + <filename>recovery.conf</filename> file in the target data directory with a + suitable <varname>restore_command</varname>. </para> <para> - <application>pg_rewind</> requires that the target server either has + <application>pg_rewind</application> requires that the target server either has the <xref linkend="guc-wal-log-hints"> option enabled - in <filename>postgresql.conf</> or data checksums enabled when - the cluster was initialized with <application>initdb</>. Neither of these + in <filename>postgresql.conf</filename> or data checksums enabled when + the cluster was initialized with <application>initdb</application>. Neither of these are currently on by default. <xref linkend="guc-full-page-writes"> - must also be set to <literal>on</>, but is enabled by default. + must also be set to <literal>on</literal>, but is enabled by default. </para> </refsect1> @@ -133,7 +133,7 @@ PostgreSQL documentation <listitem> <para> Specifies a libpq connection string to connect to the source - <productname>PostgreSQL</> server to synchronize the target with. + <productname>PostgreSQL</productname> server to synchronize the target with. The connection must be a normal (non-replication) connection with superuser access. This option requires the source server to be running and not in recovery mode. @@ -167,7 +167,7 @@ PostgreSQL documentation <listitem> <para> Print verbose debugging output that is mostly useful for developers - debugging <application>pg_rewind</>. + debugging <application>pg_rewind</application>. </para> </listitem> </varlistentry> @@ -192,9 +192,9 @@ PostgreSQL documentation <title>Environment</title> <para> - When <option>--source-server</> option is used, + When <option>--source-server</option> option is used, <application>pg_rewind</application> also uses the environment variables - supported by <application>libpq</> (see <xref linkend="libpq-envars">). + supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> </refsect1> @@ -224,7 +224,7 @@ PostgreSQL documentation <para> Copy all those changed blocks from the source cluster to the target cluster, either using direct file system access - (<option>--source-pgdata</>) or SQL (<option>--source-server</>). + (<option>--source-pgdata</option>) or SQL (<option>--source-server</option>). </para> </step> <step> @@ -237,9 +237,9 @@ PostgreSQL documentation <step> <para> Apply the WAL from the source cluster, starting from the checkpoint - created at failover. (Strictly speaking, <application>pg_rewind</> + created at failover. (Strictly speaking, <application>pg_rewind</application> doesn't apply the WAL, it just creates a backup label file that - makes <productname>PostgreSQL</> start by replaying all WAL from + makes <productname>PostgreSQL</productname> start by replaying all WAL from that checkpoint forward.) </para> </step> diff --git a/doc/src/sgml/ref/pg_waldump.sgml b/doc/src/sgml/ref/pg_waldump.sgml index cff88a4c1e8..0b39726e30c 100644 --- a/doc/src/sgml/ref/pg_waldump.sgml +++ b/doc/src/sgml/ref/pg_waldump.sgml @@ -133,7 +133,7 @@ PostgreSQL documentation <listitem> <para> Only display records generated by the specified resource manager. - If <literal>list</> is passed as name, print a list of valid resource manager + If <literal>list</literal> is passed as name, print a list of valid resource manager names, and exit. </para> </listitem> @@ -156,15 +156,15 @@ PostgreSQL documentation <listitem> <para> Timeline from which to read log records. The default is to use the - value in <replaceable>startseg</>, if that is specified; otherwise, the + value in <replaceable>startseg</replaceable>, if that is specified; otherwise, the default is 1. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_waldump</application> version and exit. @@ -195,8 +195,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_waldump</application> command line @@ -220,8 +220,8 @@ PostgreSQL documentation </para> <para> - <application>pg_waldump</> cannot read WAL files with suffix - <literal>.partial</>. If those files need to be read, <literal>.partial</> + <application>pg_waldump</application> cannot read WAL files with suffix + <literal>.partial</literal>. If those files need to be read, <literal>.partial</literal> suffix needs to be removed from the file name. </para> </refsect1> diff --git a/doc/src/sgml/ref/pgarchivecleanup.sgml b/doc/src/sgml/ref/pgarchivecleanup.sgml index abe01bef4ff..65ba3df9282 100644 --- a/doc/src/sgml/ref/pgarchivecleanup.sgml +++ b/doc/src/sgml/ref/pgarchivecleanup.sgml @@ -29,44 +29,44 @@ <title>Description</title> <para> - <application>pg_archivecleanup</> is designed to be used as an + <application>pg_archivecleanup</application> is designed to be used as an <literal>archive_cleanup_command</literal> to clean up WAL file archives when running as a standby server (see <xref linkend="warm-standby">). - <application>pg_archivecleanup</> can also be used as a standalone program to + <application>pg_archivecleanup</application> can also be used as a standalone program to clean WAL file archives. </para> <para> To configure a standby - server to use <application>pg_archivecleanup</>, put this into its + server to use <application>pg_archivecleanup</application>, put this into its <filename>recovery.conf</filename> configuration file: <programlisting> -archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</> %r' +archive_cleanup_command = 'pg_archivecleanup <replaceable>archivelocation</replaceable> %r' </programlisting> - where <replaceable>archivelocation</> is the directory from which WAL segment + where <replaceable>archivelocation</replaceable> is the directory from which WAL segment files should be removed. </para> <para> When used within <xref linkend="archive-cleanup-command">, all WAL files - logically preceding the value of the <literal>%r</> argument will be removed - from <replaceable>archivelocation</>. This minimizes the number of files + logically preceding the value of the <literal>%r</literal> argument will be removed + from <replaceable>archivelocation</replaceable>. This minimizes the number of files that need to be retained, while preserving crash-restart capability. Use of - this parameter is appropriate if the <replaceable>archivelocation</> is a + this parameter is appropriate if the <replaceable>archivelocation</replaceable> is a transient staging area for this particular standby server, but - <emphasis>not</> when the <replaceable>archivelocation</> is intended as a + <emphasis>not</emphasis> when the <replaceable>archivelocation</replaceable> is intended as a long-term WAL archive area, or when multiple standby servers are recovering from the same archive location. </para> <para> When used as a standalone program all WAL files logically preceding the - <replaceable>oldestkeptwalfile</> will be removed from <replaceable>archivelocation</>. - In this mode, if you specify a <filename>.partial</> or <filename>.backup</> + <replaceable>oldestkeptwalfile</replaceable> will be removed from <replaceable>archivelocation</replaceable>. + In this mode, if you specify a <filename>.partial</filename> or <filename>.backup</filename> file name, then only the file prefix will be used as the - <replaceable>oldestkeptwalfile</>. This treatment of <filename>.backup</> + <replaceable>oldestkeptwalfile</replaceable>. This treatment of <filename>.backup</filename> file name allows you to remove all WAL files archived prior to a specific base backup without error. For example, the following example will remove all files older than - WAL file name <filename>000000010000003700000010</>: + WAL file name <filename>000000010000003700000010</filename>: <programlisting> pg_archivecleanup -d archive 000000010000003700000010.00000020.backup @@ -77,7 +77,7 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" </para> <para> <application>pg_archivecleanup</application> assumes that - <replaceable>archivelocation</> is a directory readable and writable by the + <replaceable>archivelocation</replaceable> is a directory readable and writable by the server-owning user. </para> </refsect1> @@ -94,7 +94,7 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" <term><option>-d</option></term> <listitem> <para> - Print lots of debug logging output on <filename>stderr</>. + Print lots of debug logging output on <filename>stderr</filename>. </para> </listitem> </varlistentry> @@ -103,14 +103,14 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" <term><option>-n</option></term> <listitem> <para> - Print the names of the files that would have been removed on <filename>stdout</> (performs a dry run). + Print the names of the files that would have been removed on <filename>stdout</filename> (performs a dry run). </para> </listitem> </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_archivecleanup</application> version and exit. @@ -119,7 +119,7 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" </varlistentry> <varlistentry> - <term><option>-x</option> <replaceable>extension</></term> + <term><option>-x</option> <replaceable>extension</replaceable></term> <listitem> <para> Provide an extension @@ -134,8 +134,8 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_archivecleanup</application> command line @@ -152,8 +152,8 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" <para> <application>pg_archivecleanup</application> is designed to work with - <productname>PostgreSQL</> 8.0 and later when used as a standalone utility, - or with <productname>PostgreSQL</> 9.0 and later when used as an + <productname>PostgreSQL</productname> 8.0 and later when used as a standalone utility, + or with <productname>PostgreSQL</productname> 9.0 and later when used as an archive cleanup command. </para> @@ -172,14 +172,14 @@ pg_archivecleanup: removing file "archive/00000001000000370000000E" archive_cleanup_command = 'pg_archivecleanup -d /mnt/standby/archive %r 2>>cleanup.log' </programlisting> where the archive directory is physically located on the standby server, - so that the <varname>archive_command</> is accessing it across NFS, + so that the <varname>archive_command</varname> is accessing it across NFS, but the files are local to the standby. This will: </para> <itemizedlist> <listitem> <para> - produce debugging output in <filename>cleanup.log</> + produce debugging output in <filename>cleanup.log</filename> </para> </listitem> <listitem> diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index f5db8d18d32..e509e6c7f62 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -34,12 +34,12 @@ <title>Description</title> <para> <application>pgbench</application> is a simple program for running benchmark - tests on <productname>PostgreSQL</>. It runs the same sequence of SQL + tests on <productname>PostgreSQL</productname>. It runs the same sequence of SQL commands over and over, possibly in multiple concurrent database sessions, and then calculates the average transaction rate (transactions per second). By default, <application>pgbench</application> tests a scenario that is - loosely based on TPC-B, involving five <command>SELECT</>, - <command>UPDATE</>, and <command>INSERT</> commands per transaction. + loosely based on TPC-B, involving five <command>SELECT</command>, + <command>UPDATE</command>, and <command>INSERT</command> commands per transaction. However, it is easy to test other cases by writing your own transaction script files. </para> @@ -63,7 +63,7 @@ tps = 85.296346 (excluding connections establishing) settings. The next line reports the number of transactions completed and intended (the latter being just the product of number of clients and number of transactions per client); these will be equal unless the run - failed before completion. (In <option>-T</> mode, only the actual + failed before completion. (In <option>-T</option> mode, only the actual number of transactions is printed.) The last two lines report the number of transactions per second, figured with and without counting the time to start database sessions. @@ -71,27 +71,27 @@ tps = 85.296346 (excluding connections establishing) <para> The default TPC-B-like transaction test requires specific tables to be - set up beforehand. <application>pgbench</> should be invoked with - the <option>-i</> (initialize) option to create and populate these + set up beforehand. <application>pgbench</application> should be invoked with + the <option>-i</option> (initialize) option to create and populate these tables. (When you are testing a custom script, you don't need this step, but will instead need to do whatever setup your test needs.) Initialization looks like: <programlisting> -pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbname</> +pgbench -i <optional> <replaceable>other-options</replaceable> </optional> <replaceable>dbname</replaceable> </programlisting> - where <replaceable>dbname</> is the name of the already-created - database to test in. (You may also need <option>-h</>, - <option>-p</>, and/or <option>-U</> options to specify how to + where <replaceable>dbname</replaceable> is the name of the already-created + database to test in. (You may also need <option>-h</option>, + <option>-p</option>, and/or <option>-U</option> options to specify how to connect to the database server.) </para> <caution> <para> - <literal>pgbench -i</> creates four tables <structname>pgbench_accounts</>, - <structname>pgbench_branches</>, <structname>pgbench_history</>, and - <structname>pgbench_tellers</>, + <literal>pgbench -i</literal> creates four tables <structname>pgbench_accounts</structname>, + <structname>pgbench_branches</structname>, <structname>pgbench_history</structname>, and + <structname>pgbench_tellers</structname>, destroying any existing tables of these names. Be very careful to use another database if you have tables having these names! @@ -99,7 +99,7 @@ pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbn </caution> <para> - At the default <quote>scale factor</> of 1, the tables initially + At the default <quote>scale factor</quote> of 1, the tables initially contain this many rows: <screen> table # of rows @@ -110,22 +110,22 @@ pgbench_accounts 100000 pgbench_history 0 </screen> You can (and, for most purposes, probably should) increase the number - of rows by using the <option>-s</> (scale factor) option. The - <option>-F</> (fillfactor) option might also be used at this point. + of rows by using the <option>-s</option> (scale factor) option. The + <option>-F</option> (fillfactor) option might also be used at this point. </para> <para> Once you have done the necessary setup, you can run your benchmark - with a command that doesn't include <option>-i</>, that is + with a command that doesn't include <option>-i</option>, that is <programlisting> -pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> +pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>dbname</replaceable> </programlisting> In nearly all cases, you'll need some options to make a useful test. - The most important options are <option>-c</> (number of clients), - <option>-t</> (number of transactions), <option>-T</> (time limit), - and <option>-f</> (specify a custom script file). + The most important options are <option>-c</option> (number of clients), + <option>-t</option> (number of transactions), <option>-T</option> (time limit), + and <option>-f</option> (specify a custom script file). See below for a full list. </para> </refsect1> @@ -159,13 +159,13 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-F</option> <replaceable>fillfactor</></term> - <term><option>--fillfactor=</option><replaceable>fillfactor</></term> + <term><option>-F</option> <replaceable>fillfactor</replaceable></term> + <term><option>--fillfactor=</option><replaceable>fillfactor</replaceable></term> <listitem> <para> - Create the <structname>pgbench_accounts</>, - <structname>pgbench_tellers</> and - <structname>pgbench_branches</> tables with the given fillfactor. + Create the <structname>pgbench_accounts</structname>, + <structname>pgbench_tellers</structname> and + <structname>pgbench_branches</structname> tables with the given fillfactor. Default is 100. </para> </listitem> @@ -194,13 +194,13 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-s</option> <replaceable>scale_factor</></term> - <term><option>--scale=</option><replaceable>scale_factor</></term> + <term><option>-s</option> <replaceable>scale_factor</replaceable></term> + <term><option>--scale=</option><replaceable>scale_factor</replaceable></term> <listitem> <para> Multiply the number of rows generated by the scale factor. - For example, <literal>-s 100</> will create 10,000,000 rows - in the <structname>pgbench_accounts</> table. Default is 1. + For example, <literal>-s 100</literal> will create 10,000,000 rows + in the <structname>pgbench_accounts</structname> table. Default is 1. When the scale is 20,000 or larger, the columns used to hold account identifiers (<structfield>aid</structfield> columns) will switch to using larger integers (<type>bigint</type>), @@ -262,17 +262,17 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <variablelist> <varlistentry> - <term><option>-b</> <replaceable>scriptname[@weight]</></term> - <term><option>--builtin</>=<replaceable>scriptname[@weight]</></term> + <term><option>-b</option> <replaceable>scriptname[@weight]</replaceable></term> + <term><option>--builtin</option>=<replaceable>scriptname[@weight]</replaceable></term> <listitem> <para> Add the specified built-in script to the list of executed scripts. - An optional integer weight after <literal>@</> allows to adjust the + An optional integer weight after <literal>@</literal> allows to adjust the probability of drawing the script. If not specified, it is set to 1. - Available built-in scripts are: <literal>tpcb-like</>, - <literal>simple-update</> and <literal>select-only</>. + Available built-in scripts are: <literal>tpcb-like</literal>, + <literal>simple-update</literal> and <literal>select-only</literal>. Unambiguous prefixes of built-in names are accepted. - With special name <literal>list</>, show the list of built-in scripts + With special name <literal>list</literal>, show the list of built-in scripts and exit immediately. </para> </listitem> @@ -280,8 +280,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <varlistentry> - <term><option>-c</option> <replaceable>clients</></term> - <term><option>--client=</option><replaceable>clients</></term> + <term><option>-c</option> <replaceable>clients</replaceable></term> + <term><option>--client=</option><replaceable>clients</replaceable></term> <listitem> <para> Number of clients simulated, that is, number of concurrent database @@ -313,24 +313,24 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-D</option> <replaceable>varname</><literal>=</><replaceable>value</></term> - <term><option>--define=</option><replaceable>varname</><literal>=</><replaceable>value</></term> + <term><option>-D</option> <replaceable>varname</replaceable><literal>=</literal><replaceable>value</replaceable></term> + <term><option>--define=</option><replaceable>varname</replaceable><literal>=</literal><replaceable>value</replaceable></term> <listitem> <para> Define a variable for use by a custom script (see below). - Multiple <option>-D</> options are allowed. + Multiple <option>-D</option> options are allowed. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-f</> <replaceable>filename[@weight]</></term> - <term><option>--file=</><replaceable>filename[@weight]</></term> + <term><option>-f</option> <replaceable>filename[@weight]</replaceable></term> + <term><option>--file=</option><replaceable>filename[@weight]</replaceable></term> <listitem> <para> - Add a transaction script read from <replaceable>filename</> to + Add a transaction script read from <replaceable>filename</replaceable> to the list of executed scripts. - An optional integer weight after <literal>@</> allows to adjust the + An optional integer weight after <literal>@</literal> allows to adjust the probability of drawing the test. See below for details. </para> @@ -338,8 +338,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-j</option> <replaceable>threads</></term> - <term><option>--jobs=</option><replaceable>threads</></term> + <term><option>-j</option> <replaceable>threads</replaceable></term> + <term><option>--jobs=</option><replaceable>threads</replaceable></term> <listitem> <para> Number of worker threads within <application>pgbench</application>. @@ -362,38 +362,38 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-L</option> <replaceable>limit</></term> - <term><option>--latency-limit=</option><replaceable>limit</></term> + <term><option>-L</option> <replaceable>limit</replaceable></term> + <term><option>--latency-limit=</option><replaceable>limit</replaceable></term> <listitem> <para> - Transaction which last more than <replaceable>limit</> milliseconds - are counted and reported separately, as <firstterm>late</>. + Transaction which last more than <replaceable>limit</replaceable> milliseconds + are counted and reported separately, as <firstterm>late</firstterm>. </para> <para> - When throttling is used (<option>--rate=...</>), transactions that - lag behind schedule by more than <replaceable>limit</> ms, and thus + When throttling is used (<option>--rate=...</option>), transactions that + lag behind schedule by more than <replaceable>limit</replaceable> ms, and thus have no hope of meeting the latency limit, are not sent to the server at all. They are counted and reported separately as - <firstterm>skipped</>. + <firstterm>skipped</firstterm>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-M</option> <replaceable>querymode</></term> - <term><option>--protocol=</option><replaceable>querymode</></term> + <term><option>-M</option> <replaceable>querymode</replaceable></term> + <term><option>--protocol=</option><replaceable>querymode</replaceable></term> <listitem> <para> Protocol to use for submitting queries to the server: <itemizedlist> <listitem> - <para><literal>simple</>: use simple query protocol.</para> + <para><literal>simple</literal>: use simple query protocol.</para> </listitem> <listitem> - <para><literal>extended</>: use extended query protocol.</para> + <para><literal>extended</literal>: use extended query protocol.</para> </listitem> <listitem> - <para><literal>prepared</>: use extended query protocol with prepared statements.</para> + <para><literal>prepared</literal>: use extended query protocol with prepared statements.</para> </listitem> </itemizedlist> The default is simple query protocol. (See <xref linkend="protocol"> @@ -408,11 +408,11 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <listitem> <para> Perform no vacuuming before running the test. - This option is <emphasis>necessary</> + This option is <emphasis>necessary</emphasis> if you are running a custom test scenario that does not include - the standard tables <structname>pgbench_accounts</>, - <structname>pgbench_branches</>, <structname>pgbench_history</>, and - <structname>pgbench_tellers</>. + the standard tables <structname>pgbench_accounts</structname>, + <structname>pgbench_branches</structname>, <structname>pgbench_history</structname>, and + <structname>pgbench_tellers</structname>. </para> </listitem> </varlistentry> @@ -423,20 +423,20 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <listitem> <para> Run built-in simple-update script. - Shorthand for <option>-b simple-update</>. + Shorthand for <option>-b simple-update</option>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-P</option> <replaceable>sec</></term> - <term><option>--progress=</option><replaceable>sec</></term> + <term><option>-P</option> <replaceable>sec</replaceable></term> + <term><option>--progress=</option><replaceable>sec</replaceable></term> <listitem> <para> - Show progress report every <replaceable>sec</> seconds. The report + Show progress report every <replaceable>sec</replaceable> seconds. The report includes the time since the beginning of the run, the tps since the last report, and the transaction latency average and standard - deviation since the last report. Under throttling (<option>-R</>), + deviation since the last report. Under throttling (<option>-R</option>), the latency is computed with respect to the transaction scheduled start time, not the actual transaction beginning time, thus it also includes the average schedule lag time. @@ -457,8 +457,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-R</option> <replaceable>rate</></term> - <term><option>--rate=</option><replaceable>rate</></term> + <term><option>-R</option> <replaceable>rate</replaceable></term> + <term><option>--rate=</option><replaceable>rate</replaceable></term> <listitem> <para> Execute transactions targeting the specified rate instead of running @@ -487,7 +487,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </para> <para> - If <option>--latency-limit</> is used together with <option>--rate</>, + If <option>--latency-limit</option> is used together with <option>--rate</option>, a transaction can lag behind so much that it is already over the latency limit when the previous transaction ends, because the latency is calculated from the scheduled start time. Such transactions are @@ -508,15 +508,15 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-s</option> <replaceable>scale_factor</></term> - <term><option>--scale=</option><replaceable>scale_factor</></term> + <term><option>-s</option> <replaceable>scale_factor</replaceable></term> + <term><option>--scale=</option><replaceable>scale_factor</replaceable></term> <listitem> <para> - Report the specified scale factor in <application>pgbench</>'s + Report the specified scale factor in <application>pgbench</application>'s output. With the built-in tests, this is not necessary; the correct scale factor will be detected by counting the number of - rows in the <structname>pgbench_branches</> table. - However, when testing only custom benchmarks (<option>-f</> option), + rows in the <structname>pgbench_branches</structname> table. + However, when testing only custom benchmarks (<option>-f</option> option), the scale factor will be reported as 1 unless this option is used. </para> </listitem> @@ -528,14 +528,14 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <listitem> <para> Run built-in select-only script. - Shorthand for <option>-b select-only</>. + Shorthand for <option>-b select-only</option>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-t</option> <replaceable>transactions</></term> - <term><option>--transactions=</option><replaceable>transactions</></term> + <term><option>-t</option> <replaceable>transactions</replaceable></term> + <term><option>--transactions=</option><replaceable>transactions</replaceable></term> <listitem> <para> Number of transactions each client runs. Default is 10. @@ -544,8 +544,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-T</option> <replaceable>seconds</></term> - <term><option>--time=</option><replaceable>seconds</></term> + <term><option>-T</option> <replaceable>seconds</replaceable></term> + <term><option>--time=</option><replaceable>seconds</replaceable></term> <listitem> <para> Run the test for this many seconds, rather than a fixed number of @@ -561,15 +561,15 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <listitem> <para> Vacuum all four standard tables before running the test. - With neither <option>-n</> nor <option>-v</>, <application>pgbench</application> will vacuum the - <structname>pgbench_tellers</> and <structname>pgbench_branches</> - tables, and will truncate <structname>pgbench_history</>. + With neither <option>-n</option> nor <option>-v</option>, <application>pgbench</application> will vacuum the + <structname>pgbench_tellers</structname> and <structname>pgbench_branches</structname> + tables, and will truncate <structname>pgbench_history</structname>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--aggregate-interval=<replaceable>seconds</></option></term> + <term><option>--aggregate-interval=<replaceable>seconds</replaceable></option></term> <listitem> <para> Length of aggregation interval (in seconds). May be used only @@ -580,11 +580,11 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>--log-prefix=<replaceable>prefix</></option></term> + <term><option>--log-prefix=<replaceable>prefix</replaceable></option></term> <listitem> <para> Set the filename prefix for the log files created by - <option>--log</>. The default is <literal>pgbench_log</>. + <option>--log</option>. The default is <literal>pgbench_log</literal>. </para> </listitem> </varlistentry> @@ -593,7 +593,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <term><option>--progress-timestamp</option></term> <listitem> <para> - When showing progress (option <option>-P</>), use a timestamp + When showing progress (option <option>-P</option>), use a timestamp (Unix epoch) instead of the number of seconds since the beginning of the run. The unit is in seconds, with millisecond precision after the dot. @@ -603,7 +603,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>--sampling-rate=<replaceable>rate</></option></term> + <term><option>--sampling-rate=<replaceable>rate</replaceable></option></term> <listitem> <para> Sampling rate, used when writing data into the log, to reduce the @@ -635,8 +635,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <variablelist> <varlistentry> - <term><option>-h</option> <replaceable>hostname</></term> - <term><option>--host=</option><replaceable>hostname</></term> + <term><option>-h</option> <replaceable>hostname</replaceable></term> + <term><option>--host=</option><replaceable>hostname</replaceable></term> <listitem> <para> The database server's host name @@ -645,8 +645,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-p</option> <replaceable>port</></term> - <term><option>--port=</option><replaceable>port</></term> + <term><option>-p</option> <replaceable>port</replaceable></term> + <term><option>--port=</option><replaceable>port</replaceable></term> <listitem> <para> The database server's port number @@ -655,8 +655,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-U</option> <replaceable>login</></term> - <term><option>--username=</option><replaceable>login</></term> + <term><option>-U</option> <replaceable>login</replaceable></term> + <term><option>--username=</option><replaceable>login</replaceable></term> <listitem> <para> The user name to connect as @@ -665,8 +665,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pgbench</application> version and exit. @@ -675,8 +675,8 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pgbench</application> command line @@ -694,23 +694,23 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <title>Notes</title> <refsect2> - <title>What is the <quote>Transaction</> Actually Performed in <application>pgbench</application>?</title> + <title>What is the <quote>Transaction</quote> Actually Performed in <application>pgbench</application>?</title> <para> - <application>pgbench</> executes test scripts chosen randomly + <application>pgbench</application> executes test scripts chosen randomly from a specified list. - They include built-in scripts with <option>-b</> and - user-provided custom scripts with <option>-f</>. + They include built-in scripts with <option>-b</option> and + user-provided custom scripts with <option>-f</option>. Each script may be given a relative weight specified after a - <literal>@</> so as to change its drawing probability. - The default weight is <literal>1</>. - Scripts with a weight of <literal>0</> are ignored. + <literal>@</literal> so as to change its drawing probability. + The default weight is <literal>1</literal>. + Scripts with a weight of <literal>0</literal> are ignored. </para> <para> - The default built-in transaction script (also invoked with <option>-b tpcb-like</>) - issues seven commands per transaction over randomly chosen <literal>aid</>, - <literal>tid</>, <literal>bid</> and <literal>balance</>. + The default built-in transaction script (also invoked with <option>-b tpcb-like</option>) + issues seven commands per transaction over randomly chosen <literal>aid</literal>, + <literal>tid</literal>, <literal>bid</literal> and <literal>balance</literal>. The scenario is inspired by the TPC-B benchmark, but is not actually TPC-B, hence the name. </para> @@ -726,15 +726,15 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </orderedlist> <para> - If you select the <literal>simple-update</> built-in (also <option>-N</>), + If you select the <literal>simple-update</literal> built-in (also <option>-N</option>), steps 4 and 5 aren't included in the transaction. This will avoid update contention on these tables, but it makes the test case even less like TPC-B. </para> <para> - If you select the <literal>select-only</> built-in (also <option>-S</>), - only the <command>SELECT</> is issued. + If you select the <literal>select-only</literal> built-in (also <option>-S</option>), + only the <command>SELECT</command> is issued. </para> </refsect2> @@ -745,26 +745,26 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <application>pgbench</application> has support for running custom benchmark scenarios by replacing the default transaction script (described above) with a transaction script read from a file - (<option>-f</option> option). In this case a <quote>transaction</> + (<option>-f</option> option). In this case a <quote>transaction</quote> counts as one execution of a script file. </para> <para> A script file contains one or more SQL commands terminated by semicolons. Empty lines and lines beginning with - <literal>--</> are ignored. Script files can also contain - <quote>meta commands</>, which are interpreted by <application>pgbench</> + <literal>--</literal> are ignored. Script files can also contain + <quote>meta commands</quote>, which are interpreted by <application>pgbench</application> itself, as described below. </para> <note> <para> - Before <productname>PostgreSQL</> 9.6, SQL commands in script files + Before <productname>PostgreSQL</productname> 9.6, SQL commands in script files were terminated by newlines, and so they could not be continued across - lines. Now a semicolon is <emphasis>required</> to separate consecutive + lines. Now a semicolon is <emphasis>required</emphasis> to separate consecutive SQL commands (though a SQL command does not need one if it is followed by a meta command). If you need to create a script file that works with - both old and new versions of <application>pgbench</>, be sure to write + both old and new versions of <application>pgbench</application>, be sure to write each SQL command on a single line ending with a semicolon. </para> </note> @@ -773,15 +773,15 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> There is a simple variable-substitution facility for script files. Variable names must consist of letters (including non-Latin letters), digits, and underscores. - Variables can be set by the command-line <option>-D</> option, + Variables can be set by the command-line <option>-D</option> option, explained above, or by the meta commands explained below. - In addition to any variables preset by <option>-D</> command-line options, + In addition to any variables preset by <option>-D</option> command-line options, there are a few variables that are preset automatically, listed in <xref linkend="pgbench-automatic-variables">. A value specified for these - variables using <option>-D</> takes precedence over the automatic presets. + variables using <option>-D</option> takes precedence over the automatic presets. Once set, a variable's value can be inserted into a SQL command by writing - <literal>:</><replaceable>variablename</>. When running more than + <literal>:</literal><replaceable>variablename</replaceable>. When running more than one client session, each session has its own set of variables. </para> @@ -810,7 +810,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </table> <para> - Script file meta commands begin with a backslash (<literal>\</>) and + Script file meta commands begin with a backslash (<literal>\</literal>) and normally extend to the end of the line, although they can be continued to additional lines by writing backslash-return. Arguments to a meta command are separated by white space. @@ -820,20 +820,20 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <variablelist> <varlistentry id='pgbench-metacommand-set'> <term> - <literal>\set <replaceable>varname</> <replaceable>expression</></literal> + <literal>\set <replaceable>varname</replaceable> <replaceable>expression</replaceable></literal> </term> <listitem> <para> - Sets variable <replaceable>varname</> to a value calculated - from <replaceable>expression</>. - The expression may contain integer constants such as <literal>5432</>, - double constants such as <literal>3.14159</>, - references to variables <literal>:</><replaceable>variablename</>, - unary operators (<literal>+</>, <literal>-</>) and binary operators - (<literal>+</>, <literal>-</>, <literal>*</>, <literal>/</>, - <literal>%</>) with their usual precedence and associativity, - <link linkend="pgbench-builtin-functions">function calls</>, and + Sets variable <replaceable>varname</replaceable> to a value calculated + from <replaceable>expression</replaceable>. + The expression may contain integer constants such as <literal>5432</literal>, + double constants such as <literal>3.14159</literal>, + references to variables <literal>:</literal><replaceable>variablename</replaceable>, + unary operators (<literal>+</literal>, <literal>-</literal>) and binary operators + (<literal>+</literal>, <literal>-</literal>, <literal>*</literal>, <literal>/</literal>, + <literal>%</literal>) with their usual precedence and associativity, + <link linkend="pgbench-builtin-functions">function calls</link>, and parentheses. </para> @@ -849,16 +849,16 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <varlistentry> <term> - <literal>\sleep <replaceable>number</> [ us | ms | s ]</literal> + <literal>\sleep <replaceable>number</replaceable> [ us | ms | s ]</literal> </term> <listitem> <para> Causes script execution to sleep for the specified duration in - microseconds (<literal>us</>), milliseconds (<literal>ms</>) or seconds - (<literal>s</>). If the unit is omitted then seconds are the default. - <replaceable>number</> can be either an integer constant or a - <literal>:</><replaceable>variablename</> reference to a variable + microseconds (<literal>us</literal>), milliseconds (<literal>ms</literal>) or seconds + (<literal>s</literal>). If the unit is omitted then seconds are the default. + <replaceable>number</replaceable> can be either an integer constant or a + <literal>:</literal><replaceable>variablename</replaceable> reference to a variable having an integer value. </para> @@ -872,22 +872,22 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <varlistentry> <term> - <literal>\setshell <replaceable>varname</> <replaceable>command</> [ <replaceable>argument</> ... ]</literal> + <literal>\setshell <replaceable>varname</replaceable> <replaceable>command</replaceable> [ <replaceable>argument</replaceable> ... ]</literal> </term> <listitem> <para> - Sets variable <replaceable>varname</> to the result of the shell command - <replaceable>command</> with the given <replaceable>argument</>(s). + Sets variable <replaceable>varname</replaceable> to the result of the shell command + <replaceable>command</replaceable> with the given <replaceable>argument</replaceable>(s). The command must return an integer value through its standard output. </para> <para> - <replaceable>command</> and each <replaceable>argument</> can be either - a text constant or a <literal>:</><replaceable>variablename</> reference - to a variable. If you want to use an <replaceable>argument</> starting + <replaceable>command</replaceable> and each <replaceable>argument</replaceable> can be either + a text constant or a <literal>:</literal><replaceable>variablename</replaceable> reference + to a variable. If you want to use an <replaceable>argument</replaceable> starting with a colon, write an additional colon at the beginning of - <replaceable>argument</>. + <replaceable>argument</replaceable>. </para> <para> @@ -900,7 +900,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <varlistentry> <term> - <literal>\shell <replaceable>command</> [ <replaceable>argument</> ... ]</literal> + <literal>\shell <replaceable>command</replaceable> [ <replaceable>argument</replaceable> ... ]</literal> </term> <listitem> @@ -924,7 +924,7 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> <para> The functions listed in <xref linkend="pgbench-functions"> are built - into <application>pgbench</> and may be used in expressions appearing in + into <application>pgbench</application> and may be used in expressions appearing in <link linkend="pgbench-metacommand-set"><literal>\set</literal></link>. </para> @@ -943,123 +943,123 @@ pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> </thead> <tbody> <row> - <entry><literal><function>abs(<replaceable>a</>)</></></> - <entry>same as <replaceable>a</></> - <entry>absolute value</> - <entry><literal>abs(-17)</></> - <entry><literal>17</></> + <entry><literal><function>abs(<replaceable>a</replaceable>)</function></literal></entry> + <entry>same as <replaceable>a</replaceable></entry> + <entry>absolute value</entry> + <entry><literal>abs(-17)</literal></entry> + <entry><literal>17</literal></entry> </row> <row> - <entry><literal><function>debug(<replaceable>a</>)</></></> - <entry>same as <replaceable>a</> </> - <entry>print <replaceable>a</> to <systemitem>stderr</systemitem>, - and return <replaceable>a</></> - <entry><literal>debug(5432.1)</></> - <entry><literal>5432.1</></> + <entry><literal><function>debug(<replaceable>a</replaceable>)</function></literal></entry> + <entry>same as <replaceable>a</replaceable> </entry> + <entry>print <replaceable>a</replaceable> to <systemitem>stderr</systemitem>, + and return <replaceable>a</replaceable></entry> + <entry><literal>debug(5432.1)</literal></entry> + <entry><literal>5432.1</literal></entry> </row> <row> - <entry><literal><function>double(<replaceable>i</>)</></></> - <entry>double</> - <entry>cast to double</> - <entry><literal>double(5432)</></> - <entry><literal>5432.0</></> + <entry><literal><function>double(<replaceable>i</replaceable>)</function></literal></entry> + <entry>double</entry> + <entry>cast to double</entry> + <entry><literal>double(5432)</literal></entry> + <entry><literal>5432.0</literal></entry> </row> <row> - <entry><literal><function>greatest(<replaceable>a</> [, <replaceable>...</> ] )</></></> - <entry>double if any <replaceable>a</> is double, else integer</> - <entry>largest value among arguments</> - <entry><literal>greatest(5, 4, 3, 2)</></> - <entry><literal>5</></> + <entry><literal><function>greatest(<replaceable>a</replaceable> [, <replaceable>...</replaceable> ] )</function></literal></entry> + <entry>double if any <replaceable>a</replaceable> is double, else integer</entry> + <entry>largest value among arguments</entry> + <entry><literal>greatest(5, 4, 3, 2)</literal></entry> + <entry><literal>5</literal></entry> </row> <row> - <entry><literal><function>int(<replaceable>x</>)</></></> - <entry>integer</> - <entry>cast to int</> - <entry><literal>int(5.4 + 3.8)</></> - <entry><literal>9</></> + <entry><literal><function>int(<replaceable>x</replaceable>)</function></literal></entry> + <entry>integer</entry> + <entry>cast to int</entry> + <entry><literal>int(5.4 + 3.8)</literal></entry> + <entry><literal>9</literal></entry> </row> <row> - <entry><literal><function>least(<replaceable>a</> [, <replaceable>...</> ] )</></></> - <entry>double if any <replaceable>a</> is double, else integer</> - <entry>smallest value among arguments</> - <entry><literal>least(5, 4, 3, 2.1)</></> - <entry><literal>2.1</></> + <entry><literal><function>least(<replaceable>a</replaceable> [, <replaceable>...</replaceable> ] )</function></literal></entry> + <entry>double if any <replaceable>a</replaceable> is double, else integer</entry> + <entry>smallest value among arguments</entry> + <entry><literal>least(5, 4, 3, 2.1)</literal></entry> + <entry><literal>2.1</literal></entry> </row> <row> - <entry><literal><function>pi()</></></> - <entry>double</> - <entry>value of the constant PI</> - <entry><literal>pi()</></> - <entry><literal>3.14159265358979323846</></> + <entry><literal><function>pi()</function></literal></entry> + <entry>double</entry> + <entry>value of the constant PI</entry> + <entry><literal>pi()</literal></entry> + <entry><literal>3.14159265358979323846</literal></entry> </row> <row> - <entry><literal><function>random(<replaceable>lb</>, <replaceable>ub</>)</></></> - <entry>integer</> - <entry>uniformly-distributed random integer in <literal>[lb, ub]</></> - <entry><literal>random(1, 10)</></> - <entry>an integer between <literal>1</> and <literal>10</></> + <entry><literal><function>random(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>)</function></literal></entry> + <entry>integer</entry> + <entry>uniformly-distributed random integer in <literal>[lb, ub]</literal></entry> + <entry><literal>random(1, 10)</literal></entry> + <entry>an integer between <literal>1</literal> and <literal>10</literal></entry> </row> <row> - <entry><literal><function>random_exponential(<replaceable>lb</>, <replaceable>ub</>, <replaceable>parameter</>)</></></> - <entry>integer</> - <entry>exponentially-distributed random integer in <literal>[lb, ub]</>, - see below</> - <entry><literal>random_exponential(1, 10, 3.0)</></> - <entry>an integer between <literal>1</> and <literal>10</></> + <entry><literal><function>random_exponential(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>, <replaceable>parameter</replaceable>)</function></literal></entry> + <entry>integer</entry> + <entry>exponentially-distributed random integer in <literal>[lb, ub]</literal>, + see below</entry> + <entry><literal>random_exponential(1, 10, 3.0)</literal></entry> + <entry>an integer between <literal>1</literal> and <literal>10</literal></entry> </row> <row> - <entry><literal><function>random_gaussian(<replaceable>lb</>, <replaceable>ub</>, <replaceable>parameter</>)</></></> - <entry>integer</> - <entry>Gaussian-distributed random integer in <literal>[lb, ub]</>, - see below</> - <entry><literal>random_gaussian(1, 10, 2.5)</></> - <entry>an integer between <literal>1</> and <literal>10</></> + <entry><literal><function>random_gaussian(<replaceable>lb</replaceable>, <replaceable>ub</replaceable>, <replaceable>parameter</replaceable>)</function></literal></entry> + <entry>integer</entry> + <entry>Gaussian-distributed random integer in <literal>[lb, ub]</literal>, + see below</entry> + <entry><literal>random_gaussian(1, 10, 2.5)</literal></entry> + <entry>an integer between <literal>1</literal> and <literal>10</literal></entry> </row> <row> - <entry><literal><function>sqrt(<replaceable>x</>)</></></> - <entry>double</> - <entry>square root</> - <entry><literal>sqrt(2.0)</></> - <entry><literal>1.414213562</></> + <entry><literal><function>sqrt(<replaceable>x</replaceable>)</function></literal></entry> + <entry>double</entry> + <entry>square root</entry> + <entry><literal>sqrt(2.0)</literal></entry> + <entry><literal>1.414213562</literal></entry> </row> </tbody> </tgroup> </table> <para> - The <literal>random</> function generates values using a uniform + The <literal>random</literal> function generates values using a uniform distribution, that is all the values are drawn within the specified - range with equal probability. The <literal>random_exponential</> and - <literal>random_gaussian</> functions require an additional double + range with equal probability. The <literal>random_exponential</literal> and + <literal>random_gaussian</literal> functions require an additional double parameter which determines the precise shape of the distribution. </para> <itemizedlist> <listitem> <para> - For an exponential distribution, <replaceable>parameter</> + For an exponential distribution, <replaceable>parameter</replaceable> controls the distribution by truncating a quickly-decreasing - exponential distribution at <replaceable>parameter</>, and then + exponential distribution at <replaceable>parameter</replaceable>, and then projecting onto integers between the bounds. To be precise, with <literallayout> f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) </literallayout> - Then value <replaceable>i</> between <replaceable>min</> and - <replaceable>max</> inclusive is drawn with probability: - <literal>f(i) - f(i + 1)</>. + Then value <replaceable>i</replaceable> between <replaceable>min</replaceable> and + <replaceable>max</replaceable> inclusive is drawn with probability: + <literal>f(i) - f(i + 1)</literal>. </para> <para> - Intuitively, the larger the <replaceable>parameter</>, the more - frequently values close to <replaceable>min</> are accessed, and the - less frequently values close to <replaceable>max</> are accessed. - The closer to 0 <replaceable>parameter</> is, the flatter (more + Intuitively, the larger the <replaceable>parameter</replaceable>, the more + frequently values close to <replaceable>min</replaceable> are accessed, and the + less frequently values close to <replaceable>max</replaceable> are accessed. + The closer to 0 <replaceable>parameter</replaceable> is, the flatter (more uniform) the access distribution. A crude approximation of the distribution is that the most frequent 1% - values in the range, close to <replaceable>min</>, are drawn - <replaceable>parameter</>% of the time. - The <replaceable>parameter</> value must be strictly positive. + values in the range, close to <replaceable>min</replaceable>, are drawn + <replaceable>parameter</replaceable>% of the time. + The <replaceable>parameter</replaceable> value must be strictly positive. </para> </listitem> @@ -1067,32 +1067,32 @@ f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) <para> For a Gaussian distribution, the interval is mapped onto a standard normal distribution (the classical bell-shaped Gaussian curve) truncated - at <literal>-parameter</> on the left and <literal>+parameter</> + at <literal>-parameter</literal> on the left and <literal>+parameter</literal> on the right. Values in the middle of the interval are more likely to be drawn. - To be precise, if <literal>PHI(x)</> is the cumulative distribution - function of the standard normal distribution, with mean <literal>mu</> - defined as <literal>(max + min) / 2.0</>, with + To be precise, if <literal>PHI(x)</literal> is the cumulative distribution + function of the standard normal distribution, with mean <literal>mu</literal> + defined as <literal>(max + min) / 2.0</literal>, with <literallayout> f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / (2.0 * PHI(parameter) - 1) </literallayout> - then value <replaceable>i</> between <replaceable>min</> and - <replaceable>max</> inclusive is drawn with probability: - <literal>f(i + 0.5) - f(i - 0.5)</>. - Intuitively, the larger the <replaceable>parameter</>, the more + then value <replaceable>i</replaceable> between <replaceable>min</replaceable> and + <replaceable>max</replaceable> inclusive is drawn with probability: + <literal>f(i + 0.5) - f(i - 0.5)</literal>. + Intuitively, the larger the <replaceable>parameter</replaceable>, the more frequently values close to the middle of the interval are drawn, and the - less frequently values close to the <replaceable>min</> and - <replaceable>max</> bounds. About 67% of values are drawn from the - middle <literal>1.0 / parameter</>, that is a relative - <literal>0.5 / parameter</> around the mean, and 95% in the middle - <literal>2.0 / parameter</>, that is a relative - <literal>1.0 / parameter</> around the mean; for instance, if - <replaceable>parameter</> is 4.0, 67% of values are drawn from the + less frequently values close to the <replaceable>min</replaceable> and + <replaceable>max</replaceable> bounds. About 67% of values are drawn from the + middle <literal>1.0 / parameter</literal>, that is a relative + <literal>0.5 / parameter</literal> around the mean, and 95% in the middle + <literal>2.0 / parameter</literal>, that is a relative + <literal>1.0 / parameter</literal> around the mean; for instance, if + <replaceable>parameter</replaceable> is 4.0, 67% of values are drawn from the middle quarter (1.0 / 4.0) of the interval (i.e. from - <literal>3.0 / 8.0</> to <literal>5.0 / 8.0</>) and 95% from - the middle half (<literal>2.0 / 4.0</>) of the interval (second and third - quartiles). The minimum <replaceable>parameter</> is 2.0 for performance + <literal>3.0 / 8.0</literal> to <literal>5.0 / 8.0</literal>) and 95% from + the middle half (<literal>2.0 / 4.0</literal>) of the interval (second and third + quartiles). The minimum <replaceable>parameter</replaceable> is 2.0 for performance of the Box-Muller transform. </para> </listitem> @@ -1128,21 +1128,21 @@ END; <title>Per-Transaction Logging</title> <para> - With the <option>-l</> option (but without + With the <option>-l</option> option (but without the <option>--aggregate-interval</option> option), - <application>pgbench</> writes information about each transaction + <application>pgbench</application> writes information about each transaction to a log file. The log file will be named - <filename><replaceable>prefix</>.<replaceable>nnn</></filename>, - where <replaceable>prefix</> defaults to <literal>pgbench_log</>, and - <replaceable>nnn</> is the PID of the + <filename><replaceable>prefix</replaceable>.<replaceable>nnn</replaceable></filename>, + where <replaceable>prefix</replaceable> defaults to <literal>pgbench_log</literal>, and + <replaceable>nnn</replaceable> is the PID of the <application>pgbench</application> process. - The prefix can be changed by using the <option>--log-prefix</> option. - If the <option>-j</> option is 2 or higher, so that there are multiple + The prefix can be changed by using the <option>--log-prefix</option> option. + If the <option>-j</option> option is 2 or higher, so that there are multiple worker threads, each will have its own log file. The first worker will use the same name for its log file as in the standard single worker case. The additional log files for the other workers will be named - <filename><replaceable>prefix</>.<replaceable>nnn</>.<replaceable>mmm</></filename>, - where <replaceable>mmm</> is a sequential number for each worker starting + <filename><replaceable>prefix</replaceable>.<replaceable>nnn</replaceable>.<replaceable>mmm</replaceable></filename>, + where <replaceable>mmm</replaceable> is a sequential number for each worker starting with 1. </para> @@ -1150,27 +1150,27 @@ END; The format of the log is: <synopsis> -<replaceable>client_id</> <replaceable>transaction_no</> <replaceable>time</> <replaceable>script_no</> <replaceable>time_epoch</> <replaceable>time_us</> <optional> <replaceable>schedule_lag</replaceable> </optional> +<replaceable>client_id</replaceable> <replaceable>transaction_no</replaceable> <replaceable>time</replaceable> <replaceable>script_no</replaceable> <replaceable>time_epoch</replaceable> <replaceable>time_us</replaceable> <optional> <replaceable>schedule_lag</replaceable> </optional> </synopsis> where - <replaceable>client_id</> indicates which client session ran the transaction, - <replaceable>transaction_no</> counts how many transactions have been + <replaceable>client_id</replaceable> indicates which client session ran the transaction, + <replaceable>transaction_no</replaceable> counts how many transactions have been run by that session, - <replaceable>time</> is the total elapsed transaction time in microseconds, - <replaceable>script_no</> identifies which script file was used (useful when - multiple scripts were specified with <option>-f</> or <option>-b</>), - and <replaceable>time_epoch</>/<replaceable>time_us</> are a + <replaceable>time</replaceable> is the total elapsed transaction time in microseconds, + <replaceable>script_no</replaceable> identifies which script file was used (useful when + multiple scripts were specified with <option>-f</option> or <option>-b</option>), + and <replaceable>time_epoch</replaceable>/<replaceable>time_us</replaceable> are a Unix-epoch time stamp and an offset in microseconds (suitable for creating an ISO 8601 time stamp with fractional seconds) showing when the transaction completed. - The <replaceable>schedule_lag</> field is the difference between the + The <replaceable>schedule_lag</replaceable> field is the difference between the transaction's scheduled start time, and the time it actually started, in - microseconds. It is only present when the <option>--rate</> option is used. - When both <option>--rate</> and <option>--latency-limit</> are used, - the <replaceable>time</> for a skipped transaction will be reported as - <literal>skipped</>. + microseconds. It is only present when the <option>--rate</option> option is used. + When both <option>--rate</option> and <option>--latency-limit</option> are used, + the <replaceable>time</replaceable> for a skipped transaction will be reported as + <literal>skipped</literal>. </para> <para> @@ -1182,9 +1182,9 @@ END; 0 202 2038 0 1175850569 2663 </screen> - Another example with <literal>--rate=100</> - and <literal>--latency-limit=5</> (note the additional - <replaceable>schedule_lag</> column): + Another example with <literal>--rate=100</literal> + and <literal>--latency-limit=5</literal> (note the additional + <replaceable>schedule_lag</replaceable> column): <screen> 0 81 4621 0 1412881037 912698 3005 0 82 6173 0 1412881037 914578 4304 @@ -1201,7 +1201,7 @@ END; <para> When running a long test on hardware that can handle a lot of transactions, - the log files can become very large. The <option>--sampling-rate</> option + the log files can become very large. The <option>--sampling-rate</option> option can be used to log only a random sample of transactions. </para> </refsect2> @@ -1214,30 +1214,30 @@ END; format is used for the log files: <synopsis> -<replaceable>interval_start</> <replaceable>num_transactions</> <replaceable>sum_latency</> <replaceable>sum_latency_2</> <replaceable>min_latency</> <replaceable>max_latency</> <optional> <replaceable>sum_lag</> <replaceable>sum_lag_2</> <replaceable>min_lag</> <replaceable>max_lag</> <optional> <replaceable>skipped</> </optional> </optional> +<replaceable>interval_start</replaceable> <replaceable>num_transactions</replaceable> <replaceable>sum_latency</replaceable> <replaceable>sum_latency_2</replaceable> <replaceable>min_latency</replaceable> <replaceable>max_latency</replaceable> <optional> <replaceable>sum_lag</replaceable> <replaceable>sum_lag_2</replaceable> <replaceable>min_lag</replaceable> <replaceable>max_lag</replaceable> <optional> <replaceable>skipped</replaceable> </optional> </optional> </synopsis> where - <replaceable>interval_start</> is the start of the interval (as a Unix + <replaceable>interval_start</replaceable> is the start of the interval (as a Unix epoch time stamp), - <replaceable>num_transactions</> is the number of transactions + <replaceable>num_transactions</replaceable> is the number of transactions within the interval, <replaceable>sum_latency</replaceable> is the sum of the transaction latencies within the interval, <replaceable>sum_latency_2</replaceable> is the sum of squares of the transaction latencies within the interval, - <replaceable>min_latency</> is the minimum latency within the interval, + <replaceable>min_latency</replaceable> is the minimum latency within the interval, and - <replaceable>max_latency</> is the maximum latency within the interval. + <replaceable>max_latency</replaceable> is the maximum latency within the interval. The next fields, - <replaceable>sum_lag</>, <replaceable>sum_lag_2</>, <replaceable>min_lag</>, - and <replaceable>max_lag</>, are only present if the <option>--rate</> + <replaceable>sum_lag</replaceable>, <replaceable>sum_lag_2</replaceable>, <replaceable>min_lag</replaceable>, + and <replaceable>max_lag</replaceable>, are only present if the <option>--rate</option> option is used. They provide statistics about the time each transaction had to wait for the previous one to finish, i.e. the difference between each transaction's scheduled start time and the time it actually started. - The very last field, <replaceable>skipped</>, - is only present if the <option>--latency-limit</> option is used, too. + The very last field, <replaceable>skipped</replaceable>, + is only present if the <option>--latency-limit</option> option is used, too. It counts the number of transactions skipped because they would have started too late. Each transaction is counted in the interval when it was committed. @@ -1265,7 +1265,7 @@ END; <title>Per-Statement Latencies</title> <para> - With the <option>-r</> option, <application>pgbench</> collects + With the <option>-r</option> option, <application>pgbench</application> collects the elapsed transaction time of each statement executed by every client. It then reports an average of those values, referred to as the latency for each statement, after the benchmark has finished. @@ -1321,14 +1321,14 @@ script statistics: <title>Good Practices</title> <para> - It is very easy to use <application>pgbench</> to produce completely + It is very easy to use <application>pgbench</application> to produce completely meaningless numbers. Here are some guidelines to help you get useful results. </para> <para> - In the first place, <emphasis>never</> believe any test that runs - for only a few seconds. Use the <option>-t</> or <option>-T</> option + In the first place, <emphasis>never</emphasis> believe any test that runs + for only a few seconds. Use the <option>-t</option> or <option>-T</option> option to make the run last at least a few minutes, so as to average out noise. In some cases you could need hours to get numbers that are reproducible. It's a good idea to try the test run a few times, to find out if your @@ -1337,11 +1337,11 @@ script statistics: <para> For the default TPC-B-like test scenario, the initialization scale factor - (<option>-s</>) should be at least as large as the largest number of - clients you intend to test (<option>-c</>); else you'll mostly be - measuring update contention. There are only <option>-s</> rows in - the <structname>pgbench_branches</> table, and every transaction wants to - update one of them, so <option>-c</> values in excess of <option>-s</> + (<option>-s</option>) should be at least as large as the largest number of + clients you intend to test (<option>-c</option>); else you'll mostly be + measuring update contention. There are only <option>-s</option> rows in + the <structname>pgbench_branches</structname> table, and every transaction wants to + update one of them, so <option>-c</option> values in excess of <option>-s</option> will undoubtedly result in lots of transactions blocked waiting for other transactions. </para> @@ -1356,11 +1356,11 @@ script statistics: </para> <para> - A limitation of <application>pgbench</> is that it can itself become + A limitation of <application>pgbench</application> is that it can itself become the bottleneck when trying to test a large number of client sessions. - This can be alleviated by running <application>pgbench</> on a different + This can be alleviated by running <application>pgbench</application> on a different machine from the database server, although low network latency will be - essential. It might even be useful to run several <application>pgbench</> + essential. It might even be useful to run several <application>pgbench</application> instances concurrently, on several client machines, against the same database server. </para> diff --git a/doc/src/sgml/ref/pgtestfsync.sgml b/doc/src/sgml/ref/pgtestfsync.sgml index 467d6e647a2..811438ceaf3 100644 --- a/doc/src/sgml/ref/pgtestfsync.sgml +++ b/doc/src/sgml/ref/pgtestfsync.sgml @@ -27,7 +27,7 @@ <title>Description</title> <para> - <application>pg_test_fsync</> is intended to give you a reasonable + <application>pg_test_fsync</application> is intended to give you a reasonable idea of what the fastest <xref linkend="guc-wal-sync-method"> is on your specific system, as well as supplying diagnostic information in the event of an identified I/O @@ -57,9 +57,9 @@ <para> Specifies the file name to write test data in. This file should be in the same file system that the - <filename>pg_wal</> directory is or will be placed in. - (<filename>pg_wal</> contains the <acronym>WAL</> files.) - The default is <filename>pg_test_fsync.out</> in the current + <filename>pg_wal</filename> directory is or will be placed in. + (<filename>pg_wal</filename> contains the <acronym>WAL</acronym> files.) + The default is <filename>pg_test_fsync.out</filename> in the current directory. </para> </listitem> @@ -79,8 +79,8 @@ </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_test_fsync</application> version and exit. @@ -89,8 +89,8 @@ </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_test_fsync</application> command line diff --git a/doc/src/sgml/ref/pgtesttiming.sgml b/doc/src/sgml/ref/pgtesttiming.sgml index c659101361a..966546747e0 100644 --- a/doc/src/sgml/ref/pgtesttiming.sgml +++ b/doc/src/sgml/ref/pgtesttiming.sgml @@ -27,7 +27,7 @@ <title>Description</title> <para> - <application>pg_test_timing</> is a tool to measure the timing overhead + <application>pg_test_timing</application> is a tool to measure the timing overhead on your system and confirm that the system time never moves backwards. Systems that are slow to collect timing data can give less accurate <command>EXPLAIN ANALYZE</command> results. @@ -57,8 +57,8 @@ </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>pg_test_timing</application> version and exit. @@ -67,8 +67,8 @@ </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>pg_test_timing</application> command line diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml index c3df343571f..8785a3ded2f 100644 --- a/doc/src/sgml/ref/pgupgrade.sgml +++ b/doc/src/sgml/ref/pgupgrade.sgml @@ -35,38 +35,38 @@ <title>Description</title> <para> - <application>pg_upgrade</> (formerly called <application>pg_migrator</>) allows data - stored in <productname>PostgreSQL</> data files to be upgraded to a later <productname>PostgreSQL</> + <application>pg_upgrade</application> (formerly called <application>pg_migrator</application>) allows data + stored in <productname>PostgreSQL</productname> data files to be upgraded to a later <productname>PostgreSQL</productname> major version without the data dump/reload typically required for major version upgrades, e.g. from 9.6.3 to the current major release - of <productname>PostgreSQL</>. It is not required for minor version upgrades, e.g. from + of <productname>PostgreSQL</productname>. It is not required for minor version upgrades, e.g. from 9.6.2 to 9.6.3. </para> <para> Major PostgreSQL releases regularly add new features that often change the layout of the system tables, but the internal data storage - format rarely changes. <application>pg_upgrade</> uses this fact + format rarely changes. <application>pg_upgrade</application> uses this fact to perform rapid upgrades by creating new system tables and simply reusing the old user data files. If a future major release ever changes the data storage format in a way that makes the old data - format unreadable, <application>pg_upgrade</> will not be usable + format unreadable, <application>pg_upgrade</application> will not be usable for such upgrades. (The community will attempt to avoid such situations.) </para> <para> - <application>pg_upgrade</> does its best to + <application>pg_upgrade</application> does its best to make sure the old and new clusters are binary-compatible, e.g. by checking for compatible compile-time settings, including 32/64-bit binaries. It is important that any external modules are also binary compatible, though this cannot - be checked by <application>pg_upgrade</>. + be checked by <application>pg_upgrade</application>. </para> <para> pg_upgrade supports upgrades from 8.4.X and later to the current - major release of <productname>PostgreSQL</>, including snapshot and beta releases. + major release of <productname>PostgreSQL</productname>, including snapshot and beta releases. </para> </refsect1> @@ -79,17 +79,17 @@ <variablelist> <varlistentry> - <term><option>-b</option> <replaceable>bindir</></term> - <term><option>--old-bindir=</option><replaceable>bindir</></term> + <term><option>-b</option> <replaceable>bindir</replaceable></term> + <term><option>--old-bindir=</option><replaceable>bindir</replaceable></term> <listitem><para>the old PostgreSQL executable directory; - environment variable <envar>PGBINOLD</></para></listitem> + environment variable <envar>PGBINOLD</envar></para></listitem> </varlistentry> <varlistentry> - <term><option>-B</option> <replaceable>bindir</></term> - <term><option>--new-bindir=</option><replaceable>bindir</></term> + <term><option>-B</option> <replaceable>bindir</replaceable></term> + <term><option>--new-bindir=</option><replaceable>bindir</replaceable></term> <listitem><para>the new PostgreSQL executable directory; - environment variable <envar>PGBINNEW</></para></listitem> + environment variable <envar>PGBINNEW</envar></para></listitem> </varlistentry> <varlistentry> @@ -99,17 +99,17 @@ </varlistentry> <varlistentry> - <term><option>-d</option> <replaceable>datadir</></term> - <term><option>--old-datadir=</option><replaceable>datadir</></term> + <term><option>-d</option> <replaceable>datadir</replaceable></term> + <term><option>--old-datadir=</option><replaceable>datadir</replaceable></term> <listitem><para>the old cluster data directory; environment - variable <envar>PGDATAOLD</></para></listitem> + variable <envar>PGDATAOLD</envar></para></listitem> </varlistentry> <varlistentry> - <term><option>-D</option> <replaceable>datadir</></term> - <term><option>--new-datadir=</option><replaceable>datadir</></term> + <term><option>-D</option> <replaceable>datadir</replaceable></term> + <term><option>--new-datadir=</option><replaceable>datadir</replaceable></term> <listitem><para>the new cluster data directory; environment - variable <envar>PGDATANEW</></para></listitem> + variable <envar>PGDATANEW</envar></para></listitem> </varlistentry> <varlistentry> @@ -143,17 +143,17 @@ </varlistentry> <varlistentry> - <term><option>-p</option> <replaceable>port</></term> - <term><option>--old-port=</option><replaceable>port</></term> + <term><option>-p</option> <replaceable>port</replaceable></term> + <term><option>--old-port=</option><replaceable>port</replaceable></term> <listitem><para>the old cluster port number; environment - variable <envar>PGPORTOLD</></para></listitem> + variable <envar>PGPORTOLD</envar></para></listitem> </varlistentry> <varlistentry> - <term><option>-P</option> <replaceable>port</></term> - <term><option>--new-port=</option><replaceable>port</></term> + <term><option>-P</option> <replaceable>port</replaceable></term> + <term><option>--new-port=</option><replaceable>port</replaceable></term> <listitem><para>the new cluster port number; environment - variable <envar>PGPORTNEW</></para></listitem> + variable <envar>PGPORTNEW</envar></para></listitem> </varlistentry> <varlistentry> @@ -164,10 +164,10 @@ </varlistentry> <varlistentry> - <term><option>-U</option> <replaceable>username</></term> - <term><option>--username=</option><replaceable>username</></term> + <term><option>-U</option> <replaceable>username</replaceable></term> + <term><option>--username=</option><replaceable>username</replaceable></term> <listitem><para>cluster's install user name; environment - variable <envar>PGUSER</></para></listitem> + variable <envar>PGUSER</envar></para></listitem> </varlistentry> <varlistentry> @@ -207,17 +207,17 @@ <para> If you are using a version-specific installation directory, e.g. - <filename>/opt/PostgreSQL/&majorversion;</>, you do not need to move the old cluster. The + <filename>/opt/PostgreSQL/&majorversion;</filename>, you do not need to move the old cluster. The graphical installers all use version-specific installation directories. </para> <para> If your installation directory is not version-specific, e.g. - <filename>/usr/local/pgsql</>, it is necessary to move the current PostgreSQL install - directory so it does not interfere with the new <productname>PostgreSQL</> installation. - Once the current <productname>PostgreSQL</> server is shut down, it is safe to rename the + <filename>/usr/local/pgsql</filename>, it is necessary to move the current PostgreSQL install + directory so it does not interfere with the new <productname>PostgreSQL</productname> installation. + Once the current <productname>PostgreSQL</productname> server is shut down, it is safe to rename the PostgreSQL installation directory; assuming the old directory is - <filename>/usr/local/pgsql</>, you can do: + <filename>/usr/local/pgsql</filename>, you can do: <programlisting> mv /usr/local/pgsql /usr/local/pgsql.old @@ -230,8 +230,8 @@ mv /usr/local/pgsql /usr/local/pgsql.old <title>For source installs, build the new version</title> <para> - Build the new PostgreSQL source with <command>configure</> flags that are compatible - with the old cluster. <application>pg_upgrade</> will check <command>pg_controldata</> to make + Build the new PostgreSQL source with <command>configure</command> flags that are compatible + with the old cluster. <application>pg_upgrade</application> will check <command>pg_controldata</command> to make sure all settings are compatible before starting the upgrade. </para> </step> @@ -241,7 +241,7 @@ mv /usr/local/pgsql /usr/local/pgsql.old <para> Install the new server's binaries and support - files. <application>pg_upgrade</> is included in a default installation. + files. <application>pg_upgrade</application> is included in a default installation. </para> <para> @@ -273,7 +273,7 @@ make prefix=/usr/local/pgsql.new install into the new cluster, e.g. <filename>pgcrypto.so</filename>, whether they are from <filename>contrib</filename> or some other source. Do not install the schema definitions, e.g. - <command>CREATE EXTENSION pgcrypto</>, because these will be upgraded + <command>CREATE EXTENSION pgcrypto</command>, because these will be upgraded from the old cluster. Also, any custom full text search files (dictionary, synonym, thesaurus, stop words) must also be copied to the new cluster. @@ -284,9 +284,9 @@ make prefix=/usr/local/pgsql.new install <title>Adjust authentication</title> <para> - <command>pg_upgrade</> will connect to the old and new servers several - times, so you might want to set authentication to <literal>peer</> - in <filename>pg_hba.conf</> or use a <filename>~/.pgpass</> file + <command>pg_upgrade</command> will connect to the old and new servers several + times, so you might want to set authentication to <literal>peer</literal> + in <filename>pg_hba.conf</filename> or use a <filename>~/.pgpass</filename> file (see <xref linkend="libpq-pgpass">). </para> </step> @@ -322,23 +322,23 @@ NET STOP postgresql-&majorversion; <para> If you are upgrading standby servers using methods outlined in section <xref linkend="pgupgrade-step-replicas">, verify that the old standby - servers are caught up by running <application>pg_controldata</> + servers are caught up by running <application>pg_controldata</application> against the old primary and standby clusters. Verify that the - <quote>Latest checkpoint location</> values match in all clusters. + <quote>Latest checkpoint location</quote> values match in all clusters. (There will be a mismatch if old standby servers were shut down - before the old primary.) Also, change <varname>wal_level</> to - <literal>replica</> in the <filename>postgresql.conf</> file on the + before the old primary.) Also, change <varname>wal_level</varname> to + <literal>replica</literal> in the <filename>postgresql.conf</filename> file on the new primary cluster. </para> </step> <step> - <title>Run <application>pg_upgrade</></title> + <title>Run <application>pg_upgrade</application></title> <para> - Always run the <application>pg_upgrade</> binary of the new server, not the old one. - <application>pg_upgrade</> requires the specification of the old and new cluster's - data and executable (<filename>bin</>) directories. You can also specify + Always run the <application>pg_upgrade</application> binary of the new server, not the old one. + <application>pg_upgrade</application> requires the specification of the old and new cluster's + data and executable (<filename>bin</filename>) directories. You can also specify user and port values, and whether you want the data files linked instead of the default copy behavior. </para> @@ -349,13 +349,13 @@ NET STOP postgresql-&majorversion; your old cluster once you start the new cluster after the upgrade. Link mode also requires that the old and new cluster data directories be in the - same file system. (Tablespaces and <filename>pg_wal</> can be on - different file systems.) See <literal>pg_upgrade --help</> for a full + same file system. (Tablespaces and <filename>pg_wal</filename> can be on + different file systems.) See <literal>pg_upgrade --help</literal> for a full list of options. </para> <para> - The <option>--jobs</> option allows multiple CPU cores to be used + The <option>--jobs</option> option allows multiple CPU cores to be used for copying/linking of files and to dump and reload database schemas in parallel; a good place to start is the maximum of the number of CPU cores and tablespaces. This option can dramatically reduce the @@ -365,14 +365,14 @@ NET STOP postgresql-&majorversion; <para> For Windows users, you must be logged into an administrative account, and - then start a shell as the <literal>postgres</> user and set the proper path: + then start a shell as the <literal>postgres</literal> user and set the proper path: <programlisting> RUNAS /USER:postgres "CMD.EXE" SET PATH=%PATH%;C:\Program Files\PostgreSQL\&majorversion;\bin; </programlisting> - and then run <application>pg_upgrade</> with quoted directories, e.g.: + and then run <application>pg_upgrade</application> with quoted directories, e.g.: <programlisting> pg_upgrade.exe @@ -382,19 +382,19 @@ pg_upgrade.exe --new-bindir "C:/Program Files/PostgreSQL/&majorversion;/bin" </programlisting> - Once started, <command>pg_upgrade</> will verify the two clusters are compatible - and then do the upgrade. You can use <command>pg_upgrade --check</> + Once started, <command>pg_upgrade</command> will verify the two clusters are compatible + and then do the upgrade. You can use <command>pg_upgrade --check</command> to perform only the checks, even if the old server is still - running. <command>pg_upgrade --check</> will also outline any + running. <command>pg_upgrade --check</command> will also outline any manual adjustments you will need to make after the upgrade. If you - are going to be using link mode, you should use the <option>--link</> + are going to be using link mode, you should use the <option>--link</option> option with <option>--check</option> to enable link-mode-specific checks. - <command>pg_upgrade</> requires write permission in the current directory. + <command>pg_upgrade</command> requires write permission in the current directory. </para> <para> Obviously, no one should be accessing the clusters during the - upgrade. <application>pg_upgrade</> defaults to running servers + upgrade. <application>pg_upgrade</application> defaults to running servers on port 50432 to avoid unintended client connections. You can use the same port number for both clusters when doing an upgrade because the old and new clusters will not be running at the @@ -403,7 +403,7 @@ pg_upgrade.exe </para> <para> - If an error occurs while restoring the database schema, <command>pg_upgrade</> will + If an error occurs while restoring the database schema, <command>pg_upgrade</command> will exit and you will have to revert to the old cluster as outlined in <xref linkend="pgupgrade-step-revert"> below. To try <command>pg_upgrade</command> again, you will need to modify the old cluster so the pg_upgrade schema restore succeeds. If the problem is a @@ -420,16 +420,16 @@ pg_upgrade.exe If you used link mode and have Streaming Replication (see <xref linkend="streaming-replication">) or Log-Shipping (see <xref linkend="warm-standby">) standby servers, you can follow these steps to - quickly upgrade them. You will not be running <application>pg_upgrade</> on - the standby servers, but rather <application>rsync</> on the primary. + quickly upgrade them. You will not be running <application>pg_upgrade</application> on + the standby servers, but rather <application>rsync</application> on the primary. Do not start any servers yet. </para> <para> - If you did <emphasis>not</> use link mode, do not have or do not - want to use <application>rsync</>, or want an easier solution, skip + If you did <emphasis>not</emphasis> use link mode, do not have or do not + want to use <application>rsync</application>, or want an easier solution, skip the instructions in this section and simply recreate the standby - servers once <application>pg_upgrade</> completes and the new primary + servers once <application>pg_upgrade</application> completes and the new primary is running. </para> @@ -445,11 +445,11 @@ pg_upgrade.exe </step> <step> - <title>Make sure the new standby data directories do <emphasis>not</> exist</title> + <title>Make sure the new standby data directories do <emphasis>not</emphasis> exist</title> <para> - Make sure the new standby data directories do <emphasis>not</> - exist or are empty. If <application>initdb</> was run, delete + Make sure the new standby data directories do <emphasis>not</emphasis> + exist or are empty. If <application>initdb</application> was run, delete the standby servers' new data directories. </para> </step> @@ -477,32 +477,32 @@ pg_upgrade.exe <para> Save any configuration files from the old standbys' data - directories you need to keep, e.g. <filename>postgresql.conf</>, - <literal>recovery.conf</>, because these will be overwritten or + directories you need to keep, e.g. <filename>postgresql.conf</filename>, + <literal>recovery.conf</literal>, because these will be overwritten or removed in the next step. </para> </step> <step> - <title>Run <application>rsync</></title> + <title>Run <application>rsync</application></title> <para> When using link mode, standby servers can be quickly upgraded using - <application>rsync</>. To accomplish this, from a directory on + <application>rsync</application>. To accomplish this, from a directory on the primary server that is above the old and new database cluster - directories, run this on the <emphasis>primary</> for each standby + directories, run this on the <emphasis>primary</emphasis> for each standby server: <programlisting> rsync --archive --delete --hard-links --size-only --no-inc-recursive old_pgdata new_pgdata remote_dir </programlisting> - where <option>old_pgdata</> and <option>new_pgdata</> are relative - to the current directory on the primary, and <option>remote_dir</> - is <emphasis>above</> the old and new cluster directories + where <option>old_pgdata</option> and <option>new_pgdata</option> are relative + to the current directory on the primary, and <option>remote_dir</option> + is <emphasis>above</emphasis> the old and new cluster directories on the standby. The directory structure under the specified directories on the primary and standbys must match. Consult the - <application>rsync</> manual page for details on specifying the + <application>rsync</application> manual page for details on specifying the remote directory, e.g. <programlisting> @@ -511,37 +511,37 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/Postgr </programlisting> You can verify what the command will do using - <application>rsync</>'s <option>--dry-run</> option. While - <application>rsync</> must be run on the primary for at least one - standby, it is possible to run <application>rsync</> on an upgraded + <application>rsync</application>'s <option>--dry-run</option> option. While + <application>rsync</application> must be run on the primary for at least one + standby, it is possible to run <application>rsync</application> on an upgraded standby to upgrade other standbys, as long as the upgraded standby has not been started. </para> <para> What this does is to record the links created by - <application>pg_upgrade</>'s link mode that connect files in the + <application>pg_upgrade</application>'s link mode that connect files in the old and new clusters on the primary server. It then finds matching files in the standby's old cluster and creates links for them in the standby's new cluster. Files that were not linked on the primary are copied from the primary to the standby. (They are usually small.) This provides rapid standby upgrades. Unfortunately, - <application>rsync</> needlessly copies files associated with + <application>rsync</application> needlessly copies files associated with temporary and unlogged tables because these files don't normally exist on standby servers. </para> <para> If you have tablespaces, you will need to run a similar - <application>rsync</> command for each tablespace directory, e.g.: + <application>rsync</application> command for each tablespace directory, e.g.: <programlisting> rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tblsp/PG_9.5_201510051 \ /vol1/pg_tblsp/PG_9.6_201608131 standby.example.com:/vol1/pg_tblsp </programlisting> - If you have relocated <filename>pg_wal</> outside the data - directories, <application>rsync</> must be run on those directories + If you have relocated <filename>pg_wal</filename> outside the data + directories, <application>rsync</application> must be run on those directories too. </para> </step> @@ -551,7 +551,7 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tb <para> Configure the servers for log shipping. (You do not need to run - <function>pg_start_backup()</> and <function>pg_stop_backup()</> + <function>pg_start_backup()</function> and <function>pg_stop_backup()</function> or take a file system backup as the standbys are still synchronized with the primary.) </para> @@ -562,12 +562,12 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tb </step> <step> - <title>Restore <filename>pg_hba.conf</></title> + <title>Restore <filename>pg_hba.conf</filename></title> <para> - If you modified <filename>pg_hba.conf</>, restore its original settings. + If you modified <filename>pg_hba.conf</filename>, restore its original settings. It might also be necessary to adjust other configuration files in the new - cluster to match the old cluster, e.g. <filename>postgresql.conf</>. + cluster to match the old cluster, e.g. <filename>postgresql.conf</filename>. </para> </step> @@ -576,7 +576,7 @@ rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/pg_tb <para> The new server can now be safely started, and then any - <application>rsync</>'ed standby servers. + <application>rsync</application>'ed standby servers. </para> </step> @@ -612,7 +612,7 @@ psql --username=postgres --file=script.sql postgres <title>Statistics</title> <para> - Because optimizer statistics are not transferred by <command>pg_upgrade</>, you will + Because optimizer statistics are not transferred by <command>pg_upgrade</command>, you will be instructed to run a command to regenerate that information at the end of the upgrade. You might need to set connection parameters to match your new cluster. @@ -628,7 +628,7 @@ psql --username=postgres --file=script.sql postgres <command>pg_upgrade</command> completes. (Automatic deletion is not possible if you have user-defined tablespaces inside the old data directory.) You can also delete the old installation directories - (e.g. <filename>bin</>, <filename>share</>). + (e.g. <filename>bin</filename>, <filename>share</filename>). </para> </step> @@ -643,7 +643,7 @@ psql --username=postgres --file=script.sql postgres <listitem> <para> If you ran <command>pg_upgrade</command> - with <option>--check</>, no modifications were made to the old + with <option>--check</option>, no modifications were made to the old cluster and you can re-use it anytime. </para> </listitem> @@ -651,7 +651,7 @@ psql --username=postgres --file=script.sql postgres <listitem> <para> If you ran <command>pg_upgrade</command> - with <option>--link</>, the data files are shared between the + with <option>--link</option>, the data files are shared between the old and new cluster. If you started the new cluster, the new server has written to those shared files and it is unsafe to use the old cluster. @@ -660,13 +660,13 @@ psql --username=postgres --file=script.sql postgres <listitem> <para> - If you ran <command>pg_upgrade</command> <emphasis>without</> - <option>--link</> or did not start the new server, the + If you ran <command>pg_upgrade</command> <emphasis>without</emphasis> + <option>--link</option> or did not start the new server, the old cluster was not modified except that, if linking - started, a <literal>.old</> suffix was appended to - <filename>$PGDATA/global/pg_control</>. To reuse the old - cluster, possibly remove the <filename>.old</> suffix from - <filename>$PGDATA/global/pg_control</>; you can then restart the + started, a <literal>.old</literal> suffix was appended to + <filename>$PGDATA/global/pg_control</filename>. To reuse the old + cluster, possibly remove the <filename>.old</filename> suffix from + <filename>$PGDATA/global/pg_control</filename>; you can then restart the old cluster. </para> </listitem> @@ -681,16 +681,16 @@ psql --username=postgres --file=script.sql postgres <title>Notes</title> <para> - <application>pg_upgrade</> does not support upgrading of databases - containing these <type>reg*</> OID-referencing system data types: - <type>regproc</>, <type>regprocedure</>, <type>regoper</>, - <type>regoperator</>, <type>regconfig</>, and - <type>regdictionary</>. (<type>regtype</> can be upgraded.) + <application>pg_upgrade</application> does not support upgrading of databases + containing these <type>reg*</type> OID-referencing system data types: + <type>regproc</type>, <type>regprocedure</type>, <type>regoper</type>, + <type>regoperator</type>, <type>regconfig</type>, and + <type>regdictionary</type>. (<type>regtype</type> can be upgraded.) </para> <para> All failure, rebuild, and reindex cases will be reported by - <application>pg_upgrade</> if they affect your installation; + <application>pg_upgrade</application> if they affect your installation; post-upgrade scripts to rebuild tables and indexes will be generated automatically. If you are trying to automate the upgrade of many clusters, you should find that clusters with identical database @@ -705,17 +705,17 @@ psql --username=postgres --file=script.sql postgres </para> <para> - If you are upgrading a pre-<productname>PostgreSQL</> 9.2 cluster + If you are upgrading a pre-<productname>PostgreSQL</productname> 9.2 cluster that uses a configuration-file-only directory, you must pass the - real data directory location to <application>pg_upgrade</>, and + real data directory location to <application>pg_upgrade</application>, and pass the configuration directory location to the server, e.g. - <literal>-d /real-data-directory -o '-D /configuration-directory'</>. + <literal>-d /real-data-directory -o '-D /configuration-directory'</literal>. </para> <para> If using a pre-9.1 old server that is using a non-default Unix-domain socket directory or a default that differs from the default of the - new cluster, set <envar>PGHOST</> to point to the old server's socket + new cluster, set <envar>PGHOST</envar> to point to the old server's socket location. (This is not relevant on Windows.) </para> @@ -723,13 +723,13 @@ psql --username=postgres --file=script.sql postgres If you want to use link mode and you do not want your old cluster to be modified when the new cluster is started, make a copy of the old cluster and upgrade that in link mode. To make a valid copy - of the old cluster, use <command>rsync</> to create a dirty + of the old cluster, use <command>rsync</command> to create a dirty copy of the old cluster while the server is running, then shut down - the old server and run <command>rsync --checksum</> again to update the - copy with any changes to make it consistent. (<option>--checksum</> - is necessary because <command>rsync</> only has file modification-time + the old server and run <command>rsync --checksum</command> again to update the + copy with any changes to make it consistent. (<option>--checksum</option> + is necessary because <command>rsync</command> only has file modification-time granularity of one second.) You might want to exclude some - files, e.g. <filename>postmaster.pid</>, as documented in <xref + files, e.g. <filename>postmaster.pid</filename>, as documented in <xref linkend="backup-lowlevel-base-backup">. If your file system supports file system snapshots or copy-on-write file copies, you can use that to make a backup of the old cluster and tablespaces, though the snapshot diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index fc11aa14a60..b62e626e7af 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <cmdsynopsis> <command>postgres</command> - <arg rep="repeat"><replaceable>option</></arg> + <arg rep="repeat"><replaceable>option</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> @@ -92,7 +92,7 @@ PostgreSQL documentation can also be set from the connecting client in an application-dependent way to apply only for that session. For example, if the environment variable <envar>PGOPTIONS</envar> is - set, then <application>libpq</>-based clients will pass that + set, then <application>libpq</application>-based clients will pass that string to the server, which will interpret it as <command>postgres</command> command-line options. </para> @@ -122,7 +122,7 @@ PostgreSQL documentation supported by <productname>PostgreSQL</productname> are described in <xref linkend="runtime-config">. Most of the other command line options are in fact short forms of such a - parameter assignment. <option>-c</> can appear multiple times + parameter assignment. <option>-c</option> can appear multiple times to set multiple parameters. </para> </listitem> @@ -133,9 +133,9 @@ PostgreSQL documentation <listitem> <para> Prints the value of the named run-time parameter, and exits. - (See the <option>-c</> option above for details.) This can + (See the <option>-c</option> option above for details.) This can be used on a running server, and returns values from - <filename>postgresql.conf</>, modified by any parameters + <filename>postgresql.conf</filename>, modified by any parameters supplied in this invocation. It does not reflect parameters supplied when the cluster was started. </para> @@ -157,7 +157,7 @@ PostgreSQL documentation debugging output is written to the server log. Values are from 1 to 5. It is also possible to pass <literal>-d 0</literal> for a specific session, which will prevent the - server log level of the parent <command>postgres</> process from being + server log level of the parent <command>postgres</command> process from being propagated to this session. </para> </listitem> @@ -179,7 +179,7 @@ PostgreSQL documentation <listitem> <para> Sets the default date style to <quote>European</quote>, that is - <literal>DMY</> ordering of input date fields. This also causes + <literal>DMY</literal> ordering of input date fields. This also causes the day to be printed before the month in certain date output formats. See <xref linkend="datatype-datetime"> for more information. </para> @@ -206,7 +206,7 @@ PostgreSQL documentation Specifies the IP host name or address on which <command>postgres</command> is to listen for TCP/IP connections from client applications. The value can also be a - comma-separated list of addresses, or <literal>*</> to specify + comma-separated list of addresses, or <literal>*</literal> to specify listening on all available interfaces. An empty value specifies not listening on any IP addresses, in which case only Unix-domain sockets can be used to connect to the @@ -225,13 +225,13 @@ PostgreSQL documentation Allows remote clients to connect via TCP/IP (Internet domain) connections. Without this option, only local connections are accepted. This option is equivalent to setting - <varname>listen_addresses</> to <literal>*</> in - <filename>postgresql.conf</> or via <option>-h</>. + <varname>listen_addresses</varname> to <literal>*</literal> in + <filename>postgresql.conf</filename> or via <option>-h</option>. </para> <para> This option is deprecated since it does not allow access to the full functionality of <xref linkend="guc-listen-addresses">. - It's usually better to set <varname>listen_addresses</> directly. + It's usually better to set <varname>listen_addresses</varname> directly. </para> </listitem> </varlistentry> @@ -291,11 +291,11 @@ PostgreSQL documentation </para> <para> - Spaces within <replaceable class="parameter">extra-options</> are + Spaces within <replaceable class="parameter">extra-options</replaceable> are considered to separate arguments, unless escaped with a backslash - (<literal>\</>); write <literal>\\</> to represent a literal + (<literal>\</literal>); write <literal>\\</literal> to represent a literal backslash. Multiple arguments can also be specified via multiple - uses of <option>-o</>. + uses of <option>-o</option>. </para> <para> @@ -340,15 +340,15 @@ PostgreSQL documentation <para> Specifies the amount of memory to be used by internal sorts and hashes before resorting to temporary disk files. See the description of the - <varname>work_mem</> configuration parameter in <xref + <varname>work_mem</varname> configuration parameter in <xref linkend="runtime-config-resource-memory">. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>postgres</application> version and exit. @@ -361,7 +361,7 @@ PostgreSQL documentation <listitem> <para> Sets a named run-time parameter; a shorter form of - <option>-c</>. + <option>-c</option>. </para> </listitem> </varlistentry> @@ -371,15 +371,15 @@ PostgreSQL documentation <listitem> <para> This option dumps out the server's internal configuration variables, - descriptions, and defaults in tab-delimited <command>COPY</> format. + descriptions, and defaults in tab-delimited <command>COPY</command> format. It is designed primarily for use by administration tools. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>postgres</application> command line @@ -643,13 +643,13 @@ PostgreSQL documentation <title>Diagnostics</title> <para> - A failure message mentioning <literal>semget</> or - <literal>shmget</> probably indicates you need to configure your + A failure message mentioning <literal>semget</literal> or + <literal>shmget</literal> probably indicates you need to configure your kernel to provide adequate shared memory and semaphores. For more discussion see <xref linkend="kernel-resources">. You might be able to postpone reconfiguring your kernel by decreasing <xref linkend="guc-shared-buffers"> to reduce the shared memory - consumption of <productname>PostgreSQL</>, and/or by reducing + consumption of <productname>PostgreSQL</productname>, and/or by reducing <xref linkend="guc-max-connections"> to reduce the semaphore consumption. </para> @@ -725,7 +725,7 @@ PostgreSQL documentation To cancel a running query, send the <literal>SIGINT</literal> signal to the process running that command. To terminate a backend process cleanly, send <literal>SIGTERM</literal> to that process. See - also <function>pg_cancel_backend</> and <function>pg_terminate_backend</> + also <function>pg_cancel_backend</function> and <function>pg_terminate_backend</function> in <xref linkend="functions-admin-signal"> for the SQL-callable equivalents of these two actions. </para> @@ -745,9 +745,9 @@ PostgreSQL documentation <refsect1 id="app-postgres-bugs"> <title>Bugs</title> <para> - The <option>--</> options will not work on <systemitem - class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>. - Use <option>-c</> instead. This is a bug in the affected operating + The <option>--</option> options will not work on <systemitem + class="osname">FreeBSD</systemitem> or <systemitem class="osname">OpenBSD</systemitem>. + Use <option>-c</option> instead. This is a bug in the affected operating systems; a future release of <productname>PostgreSQL</productname> will provide a workaround if this is not fixed. </para> @@ -759,17 +759,17 @@ PostgreSQL documentation <para> To start a single-user mode server, use a command like <screen> -<userinput>postgres --single -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput> +<userinput>postgres --single -D /usr/local/pgsql/data <replaceable>other-options</replaceable> my_database</userinput> </screen> - Provide the correct path to the database directory with <option>-D</>, or - make sure that the environment variable <envar>PGDATA</> is set. + Provide the correct path to the database directory with <option>-D</option>, or + make sure that the environment variable <envar>PGDATA</envar> is set. Also specify the name of the particular database you want to work in. </para> <para> Normally, the single-user mode server treats newline as the command entry terminator; there is no intelligence about semicolons, - as there is in <application>psql</>. To continue a command + as there is in <application>psql</application>. To continue a command across multiple lines, you must type backslash just before each newline except the last one. The backslash and adjacent newline are both dropped from the input command. Note that this will happen even @@ -777,7 +777,7 @@ PostgreSQL documentation </para> <para> - But if you use the <option>-j</> command line switch, a single newline + But if you use the <option>-j</option> command line switch, a single newline does not terminate command entry; instead, the sequence semicolon-newline-newline does. That is, type a semicolon immediately followed by a completely empty line. Backslash-newline is not @@ -794,10 +794,10 @@ PostgreSQL documentation <para> To quit the session, type <acronym>EOF</acronym> - (<keycombo action="simul"><keycap>Control</><keycap>D</></>, usually). + (<keycombo action="simul"><keycap>Control</keycap><keycap>D</keycap></keycombo>, usually). If you've entered any text since the last command entry terminator, then <acronym>EOF</acronym> will be taken as a command entry terminator, - and another <acronym>EOF</> will be needed to exit. + and another <acronym>EOF</acronym> will be needed to exit. </para> <para> @@ -826,7 +826,7 @@ PostgreSQL documentation <screen> <prompt>$</prompt> <userinput>postgres -p 1234</userinput> </screen> - To connect to this server using <application>psql</>, specify this port with the -p option: + To connect to this server using <application>psql</application>, specify this port with the -p option: <screen> <prompt>$</prompt> <userinput>psql -p 1234</userinput> </screen> @@ -844,11 +844,11 @@ PostgreSQL documentation <prompt>$</prompt> <userinput>postgres --work-mem=1234</userinput> </screen> Either form overrides whatever setting might exist for - <varname>work_mem</> in <filename>postgresql.conf</>. Notice that + <varname>work_mem</varname> in <filename>postgresql.conf</filename>. Notice that underscores in parameter names can be written as either underscore or dash on the command line. Except for short-term experiments, it's probably better practice to edit the setting in - <filename>postgresql.conf</> than to rely on a command-line switch + <filename>postgresql.conf</filename> than to rely on a command-line switch to set a parameter. </para> </refsect1> diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml index 0a58a633312..ec11ec65f55 100644 --- a/doc/src/sgml/ref/postmaster.sgml +++ b/doc/src/sgml/ref/postmaster.sgml @@ -22,7 +22,7 @@ PostgreSQL documentation <refsynopsisdiv> <cmdsynopsis> <command>postmaster</command> - <arg rep="repeat"><replaceable>option</></arg> + <arg rep="repeat"><replaceable>option</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> diff --git a/doc/src/sgml/ref/prepare.sgml b/doc/src/sgml/ref/prepare.sgml index f4e1d543492..bcf188f4b94 100644 --- a/doc/src/sgml/ref/prepare.sgml +++ b/doc/src/sgml/ref/prepare.sgml @@ -48,7 +48,7 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class 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 - <literal>$1</>, <literal>$2</>, etc. A corresponding list of + <literal>$1</literal>, <literal>$2</literal>, etc. A corresponding list of parameter data types can optionally be specified. When a parameter's data type is not specified or is declared as <literal>unknown</literal>, the type is inferred from the context @@ -115,8 +115,8 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class <term><replaceable class="parameter">statement</replaceable></term> <listitem> <para> - Any <command>SELECT</>, <command>INSERT</>, <command>UPDATE</>, - <command>DELETE</>, or <command>VALUES</> statement. + Any <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>, + <command>DELETE</command>, or <command>VALUES</command> statement. </para> </listitem> </varlistentry> @@ -155,9 +155,9 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class <para> To examine the query plan <productname>PostgreSQL</productname> is using for a prepared statement, use <xref linkend="sql-explain">, e.g. - <command>EXPLAIN EXECUTE</>. + <command>EXPLAIN EXECUTE</command>. If a generic plan is in use, it will contain parameter symbols - <literal>$<replaceable>n</></literal>, while a custom plan will have the + <literal>$<replaceable>n</replaceable></literal>, while a custom plan will have the supplied parameter values substituted into it. The row estimates in the generic plan reflect the selectivity computed for the parameters. @@ -172,13 +172,13 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class <para> Although the main point of a prepared statement is to avoid repeated parse - analysis and planning of the statement, <productname>PostgreSQL</> will + analysis and planning of the statement, <productname>PostgreSQL</productname> 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 since the previous use of the prepared statement. Also, if the value of <xref linkend="guc-search-path"> changes from one use to the next, the statement will be re-parsed using the new - <varname>search_path</>. (This latter behavior is new as of + <varname>search_path</varname>. (This latter behavior is new as of <productname>PostgreSQL</productname> 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 @@ -186,7 +186,7 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class 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 <varname>search_path</>, no automatic re-parse will occur + earlier in the <varname>search_path</varname>, 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. @@ -222,7 +222,7 @@ EXECUTE usrrptplan(1, current_date); </programlisting> Note that the data type of the second parameter is not specified, - so it is inferred from the context in which <literal>$2</> is used. + so it is inferred from the context in which <literal>$2</literal> is used. </para> </refsect1> <refsect1> diff --git a/doc/src/sgml/ref/prepare_transaction.sgml b/doc/src/sgml/ref/prepare_transaction.sgml index 9a2e38e98c7..4f78e6b1313 100644 --- a/doc/src/sgml/ref/prepare_transaction.sgml +++ b/doc/src/sgml/ref/prepare_transaction.sgml @@ -47,7 +47,7 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> <para> From the point of view of the issuing session, <command>PREPARE - TRANSACTION</command> is not unlike a <command>ROLLBACK</> command: + TRANSACTION</command> is not unlike a <command>ROLLBACK</command> 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.) @@ -55,7 +55,7 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> <para> If the <command>PREPARE TRANSACTION</command> command fails for any - reason, it becomes a <command>ROLLBACK</>: the current transaction + reason, it becomes a <command>ROLLBACK</command>: the current transaction is canceled. </para> </refsect1> @@ -69,7 +69,7 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> <listitem> <para> An arbitrary identifier that later identifies this transaction for - <command>COMMIT PREPARED</> or <command>ROLLBACK PREPARED</>. + <command>COMMIT PREPARED</command> or <command>ROLLBACK PREPARED</command>. 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. @@ -83,12 +83,12 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> <title>Notes</title> <para> - <command>PREPARE TRANSACTION</> is not intended for use in applications + <command>PREPARE TRANSACTION</command> 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're writing a transaction manager, you probably shouldn't be using <command>PREPARE - TRANSACTION</>. + TRANSACTION</command>. </para> <para> @@ -97,22 +97,22 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> </para> <para> - It is not currently allowed to <command>PREPARE</> a transaction that + It is not currently allowed to <command>PREPARE</command> a transaction that has executed any operations involving temporary tables, - created any cursors <literal>WITH HOLD</>, or executed - <command>LISTEN</> or <command>UNLISTEN</>. + created any cursors <literal>WITH HOLD</literal>, or executed + <command>LISTEN</command> or <command>UNLISTEN</command>. Those features are too tightly tied to the current session to be useful in a transaction to be prepared. </para> <para> - If the transaction modified any run-time parameters with <command>SET</> - (without the <literal>LOCAL</> option), - those effects persist after <command>PREPARE TRANSACTION</>, and will not + If the transaction modified any run-time parameters with <command>SET</command> + (without the <literal>LOCAL</literal> option), + those effects persist after <command>PREPARE TRANSACTION</command>, and will not be affected by any later <command>COMMIT PREPARED</command> or <command>ROLLBACK PREPARED</command>. Thus, in this one respect - <command>PREPARE TRANSACTION</> acts more like <command>COMMIT</> than - <command>ROLLBACK</>. + <command>PREPARE TRANSACTION</command> acts more like <command>COMMIT</command> than + <command>ROLLBACK</command>. </para> <para> @@ -124,7 +124,7 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> <caution> <para> It is unwise to leave transactions in the prepared state for a long time. - This will interfere with the ability of <command>VACUUM</> to reclaim + This will interfere with the ability of <command>VACUUM</command> to reclaim storage, and in extreme cases could cause the database to shut down to prevent transaction ID wraparound (see <xref linkend="vacuum-for-wraparound">). Keep in mind also that the transaction @@ -149,7 +149,7 @@ PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable> <title id="sql-prepare-transaction-examples-title">Examples</title> <para> Prepare the current transaction for two-phase commit, using - <literal>foobar</> as the transaction identifier: + <literal>foobar</literal> as the transaction identifier: <programlisting> PREPARE TRANSACTION 'foobar'; diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index e7a3e17c67b..8cbe0569cf4 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -50,8 +50,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-a</></term> - <term><option>--echo-all</></term> + <term><option>-a</option></term> + <term><option>--echo-all</option></term> <listitem> <para> Print all nonempty input lines to standard output as they are read. @@ -63,8 +63,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-A</></term> - <term><option>--no-align</></term> + <term><option>-A</option></term> + <term><option>--no-align</option></term> <listitem> <para> Switches to unaligned output mode. (The default output mode is @@ -75,8 +75,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-b</></term> - <term><option>--echo-errors</></term> + <term><option>-b</option></term> + <term><option>--echo-errors</option></term> <listitem> <para> Print failed SQL commands to standard error output. This is @@ -87,8 +87,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-c <replaceable class="parameter">command</replaceable></></term> - <term><option>--command=<replaceable class="parameter">command</replaceable></></term> + <term><option>-c <replaceable class="parameter">command</replaceable></option></term> + <term><option>--command=<replaceable class="parameter">command</replaceable></option></term> <listitem> <para> Specifies that <application>psql</application> is to execute the given @@ -116,14 +116,14 @@ psql -c '\x' -c 'SELECT * FROM foo;' <programlisting> echo '\x \\ SELECT * FROM foo;' | psql </programlisting> - (<literal>\\</> is the separator meta-command.) + (<literal>\\</literal> is the separator meta-command.) </para> <para> Each <acronym>SQL</acronym> command string passed to <option>-c</option> is sent to the server as a single request. Because of this, the server executes it as a single transaction even if the string contains multiple <acronym>SQL</acronym> commands, - unless there are explicit <command>BEGIN</>/<command>COMMIT</> + unless there are explicit <command>BEGIN</command>/<command>COMMIT</command> commands included in the string to divide it into multiple transactions. (See <xref linkend="protocol-flow-multi-statement"> for more details about how the server handles multi-query strings.) @@ -152,8 +152,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-d <replaceable class="parameter">dbname</replaceable></></term> - <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>-d <replaceable class="parameter">dbname</replaceable></option></term> + <term><option>--dbname=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to. This is @@ -173,8 +173,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo-queries</></term> + <term><option>-e</option></term> + <term><option>--echo-queries</option></term> <listitem> <para> Copy all SQL commands sent to the server to standard output as well. @@ -186,21 +186,21 @@ EOF </varlistentry> <varlistentry> - <term><option>-E</></term> - <term><option>--echo-hidden</></term> + <term><option>-E</option></term> + <term><option>--echo-hidden</option></term> <listitem> <para> Echo the actual queries generated by <command>\d</command> and other backslash commands. You can use this to study <application>psql</application>'s internal operations. This is equivalent to - setting the variable <varname>ECHO_HIDDEN</varname> to <literal>on</>. + setting the variable <varname>ECHO_HIDDEN</varname> to <literal>on</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-f <replaceable class="parameter">filename</replaceable></></term> - <term><option>--file=<replaceable class="parameter">filename</replaceable></></term> + <term><option>-f <replaceable class="parameter">filename</replaceable></option></term> + <term><option>--file=<replaceable class="parameter">filename</replaceable></option></term> <listitem> <para> Read commands from the @@ -219,7 +219,7 @@ EOF <para> If <replaceable>filename</replaceable> is <literal>-</literal> (hyphen), then standard input is read until an EOF indication - or <command>\q</> meta-command. This can be used to intersperse + or <command>\q</command> meta-command. This can be used to intersperse interactive input with input from files. Note however that Readline is not used in this case (much as if <option>-n</option> had been specified). @@ -241,8 +241,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-F <replaceable class="parameter">separator</replaceable></></term> - <term><option>--field-separator=<replaceable class="parameter">separator</replaceable></></term> + <term><option>-F <replaceable class="parameter">separator</replaceable></option></term> + <term><option>--field-separator=<replaceable class="parameter">separator</replaceable></option></term> <listitem> <para> Use <replaceable class="parameter">separator</replaceable> as the @@ -253,8 +253,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-h <replaceable class="parameter">hostname</replaceable></></term> - <term><option>--host=<replaceable class="parameter">hostname</replaceable></></term> + <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">hostname</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the @@ -266,8 +266,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-H</></term> - <term><option>--html</></term> + <term><option>-H</option></term> + <term><option>--html</option></term> <listitem> <para> Turn on <acronym>HTML</acronym> tabular output. This is @@ -278,8 +278,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-l</></term> - <term><option>--list</></term> + <term><option>-l</option></term> + <term><option>--list</option></term> <listitem> <para> List all available databases, then exit. Other non-connection @@ -290,8 +290,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-L <replaceable class="parameter">filename</replaceable></></term> - <term><option>--log-file=<replaceable class="parameter">filename</replaceable></></term> + <term><option>-L <replaceable class="parameter">filename</replaceable></option></term> + <term><option>--log-file=<replaceable class="parameter">filename</replaceable></option></term> <listitem> <para> Write all query output into file <replaceable @@ -302,8 +302,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-n</></term> - <term><option>--no-readline</></term> + <term><option>-n</option></term> + <term><option>--no-readline</option></term> <listitem> <para> Do not use <application>Readline</application> for line editing and do @@ -314,8 +314,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-o <replaceable class="parameter">filename</replaceable></></term> - <term><option>--output=<replaceable class="parameter">filename</replaceable></></term> + <term><option>-o <replaceable class="parameter">filename</replaceable></option></term> + <term><option>--output=<replaceable class="parameter">filename</replaceable></option></term> <listitem> <para> Put all query output into file <replaceable @@ -326,8 +326,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or the local Unix-domain @@ -340,8 +340,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-P <replaceable class="parameter">assignment</replaceable></></term> - <term><option>--pset=<replaceable class="parameter">assignment</replaceable></></term> + <term><option>-P <replaceable class="parameter">assignment</replaceable></option></term> + <term><option>--pset=<replaceable class="parameter">assignment</replaceable></option></term> <listitem> <para> Specifies printing options, in the style of @@ -354,8 +354,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-q</></term> - <term><option>--quiet</></term> + <term><option>-q</option></term> + <term><option>--quiet</option></term> <listitem> <para> Specifies that <application>psql</application> should do its work @@ -363,14 +363,14 @@ EOF informational output. If this option is used, none of this happens. This is useful with the <option>-c</option> option. This is equivalent to setting the variable <varname>QUIET</varname> - to <literal>on</>. + to <literal>on</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-R <replaceable class="parameter">separator</replaceable></></term> - <term><option>--record-separator=<replaceable class="parameter">separator</replaceable></></term> + <term><option>-R <replaceable class="parameter">separator</replaceable></option></term> + <term><option>--record-separator=<replaceable class="parameter">separator</replaceable></option></term> <listitem> <para> Use <replaceable class="parameter">separator</replaceable> as the @@ -381,8 +381,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-s</></term> - <term><option>--single-step</></term> + <term><option>-s</option></term> + <term><option>--single-step</option></term> <listitem> <para> Run in single-step mode. That means the user is prompted before @@ -393,8 +393,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-S</></term> - <term><option>--single-line</></term> + <term><option>-S</option></term> + <term><option>--single-line</option></term> <listitem> <para> Runs in single-line mode where a newline terminates an SQL command, as a @@ -413,8 +413,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-t</></term> - <term><option>--tuples-only</></term> + <term><option>-t</option></term> + <term><option>--tuples-only</option></term> <listitem> <para> Turn off printing of column names and result row count footers, @@ -425,8 +425,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-T <replaceable class="parameter">table_options</replaceable></></term> - <term><option>--table-attr=<replaceable class="parameter">table_options</replaceable></></term> + <term><option>-T <replaceable class="parameter">table_options</replaceable></option></term> + <term><option>--table-attr=<replaceable class="parameter">table_options</replaceable></option></term> <listitem> <para> Specifies options to be placed within the @@ -437,8 +437,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> Connect to the database as the user <replaceable @@ -449,9 +449,9 @@ EOF </varlistentry> <varlistentry> - <term><option>-v <replaceable class="parameter">assignment</replaceable></></term> - <term><option>--set=<replaceable class="parameter">assignment</replaceable></></term> - <term><option>--variable=<replaceable class="parameter">assignment</replaceable></></term> + <term><option>-v <replaceable class="parameter">assignment</replaceable></option></term> + <term><option>--set=<replaceable class="parameter">assignment</replaceable></option></term> + <term><option>--variable=<replaceable class="parameter">assignment</replaceable></option></term> <listitem> <para> Perform a variable assignment, like the <command>\set</command> @@ -466,8 +466,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>psql</application> version and exit. @@ -476,8 +476,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires password @@ -496,8 +496,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>psql</application> to prompt for a @@ -509,7 +509,7 @@ EOF will automatically prompt for a password if the server demands password authentication. However, <application>psql</application> will waste a connection attempt finding out that the server wants a - password. In some cases it is worth typing <option>-W</> to avoid + password. In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> @@ -522,8 +522,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-x</></term> - <term><option>--expanded</></term> + <term><option>-x</option></term> + <term><option>--expanded</option></term> <listitem> <para> Turn on the expanded table formatting mode. This is equivalent to @@ -533,8 +533,8 @@ EOF </varlistentry> <varlistentry> - <term><option>-X,</></term> - <term><option>--no-psqlrc</></term> + <term><option>-X,</option></term> + <term><option>--no-psqlrc</option></term> <listitem> <para> Do not read the start-up file (neither the system-wide @@ -574,8 +574,8 @@ EOF <para> This option can only be used in combination with one or more <option>-c</option> and/or <option>-f</option> options. It causes - <application>psql</application> to issue a <command>BEGIN</> command - before the first such option and a <command>COMMIT</> command after + <application>psql</application> to issue a <command>BEGIN</command> command + before the first such option and a <command>COMMIT</command> command after the last one, thereby wrapping all the commands into a single transaction. This ensures that either all the commands complete successfully, or no changes are applied. @@ -583,8 +583,8 @@ EOF <para> If the commands themselves - contain <command>BEGIN</>, <command>COMMIT</>, - or <command>ROLLBACK</>, this option will not have the desired + contain <command>BEGIN</command>, <command>COMMIT</command>, + or <command>ROLLBACK</command>, this option will not have the desired effects. Also, if an individual command cannot be executed inside a transaction block, specifying this option will cause the whole transaction to fail. @@ -593,17 +593,17 @@ EOF </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help[=<replaceable class="parameter">topic</>]</option></term> + <term><option>-?</option></term> + <term><option>--help[=<replaceable class="parameter">topic</replaceable>]</option></term> <listitem> <para> Show help about <application>psql</application> and exit. The optional - <replaceable class="parameter">topic</> parameter (defaulting + <replaceable class="parameter">topic</replaceable> parameter (defaulting to <literal>options</literal>) selects which part of <application>psql</application> is - explained: <literal>commands</> describes <application>psql</>'s - backslash commands; <literal>options</> describes the command-line - options that can be passed to <application>psql</>; - and <literal>variables</> shows help about <application>psql</application> configuration + explained: <literal>commands</literal> describes <application>psql</application>'s + backslash commands; <literal>options</literal> describes the command-line + options that can be passed to <application>psql</application>; + and <literal>variables</literal> shows help about <application>psql</application> configuration variables. </para> </listitem> @@ -644,8 +644,8 @@ EOF not belong to any option it will be interpreted as the database name (or the user name, if the database name is already given). Not all of these options are required; there are useful defaults. If you omit the host - name, <application>psql</> will connect via a Unix-domain socket - to a server on the local host, or via TCP/IP to <literal>localhost</> on + name, <application>psql</application> will connect via a Unix-domain socket + to a server on the local host, or via TCP/IP to <literal>localhost</literal> on machines that don't have Unix-domain sockets. The default port number is determined at compile time. Since the database server uses the same default, you will not have @@ -663,7 +663,7 @@ EOF <envar>PGPORT</envar> and/or <envar>PGUSER</envar> to appropriate values. (For additional environment variables, see <xref linkend="libpq-envars">.) It is also convenient to have a - <filename>~/.pgpass</> file to avoid regularly having to type in + <filename>~/.pgpass</filename> file to avoid regularly having to type in passwords. See <xref linkend="libpq-pgpass"> for more information. </para> @@ -777,13 +777,13 @@ testdb=> <para> If an unquoted colon (<literal>:</literal>) followed by a - <application>psql</> variable name appears within an argument, it is + <application>psql</application> variable name appears within an argument, it is replaced by the variable's value, as described in <xref linkend="APP-PSQL-interpolation" endterm="APP-PSQL-interpolation-title">. - The forms <literal>:'<replaceable>variable_name</>'</literal> and - <literal>:"<replaceable>variable_name</>"</literal> described there + The forms <literal>:'<replaceable>variable_name</replaceable>'</literal> and + <literal>:"<replaceable>variable_name</replaceable>"</literal> described there work as well. - The <literal>:{?<replaceable>variable_name</>}</> syntax allows + The <literal>:{?<replaceable>variable_name</replaceable>}</literal> syntax allows testing whether a variable is defined. It is substituted by TRUE or FALSE. Escaping the colon with a backslash protects it from substitution. @@ -795,15 +795,15 @@ testdb=> shell. The output of the command (with any trailing newline removed) replaces the backquoted text. Within the text enclosed in backquotes, no special quoting or other processing occurs, except that appearances - of <literal>:<replaceable>variable_name</></literal> where - <replaceable>variable_name</> is a <application>psql</> variable name + of <literal>:<replaceable>variable_name</replaceable></literal> where + <replaceable>variable_name</replaceable> is a <application>psql</application> variable name are replaced by the variable's value. Also, appearances of - <literal>:'<replaceable>variable_name</>'</literal> are replaced by the + <literal>:'<replaceable>variable_name</replaceable>'</literal> are replaced by the variable's value suitably quoted to become a single shell command argument. (The latter form is almost always preferable, unless you are very sure of what is in the variable.) Because carriage return and line feed characters cannot be safely quoted on all platforms, the - <literal>:'<replaceable>variable_name</>'</literal> form prints an + <literal>:'<replaceable>variable_name</replaceable>'</literal> form prints an error message and does not substitute the variable value when such characters appear in the value. </para> @@ -812,13 +812,13 @@ testdb=> Some commands take an <acronym>SQL</acronym> identifier (such as a table name) as argument. These arguments follow the syntax rules of <acronym>SQL</acronym>: Unquoted letters are forced to - lowercase, while double quotes (<literal>"</>) protect letters + lowercase, while double quotes (<literal>"</literal>) protect letters from case conversion and allow incorporation of whitespace into the identifier. Within double quotes, paired double quotes reduce to a single double quote in the resulting name. For example, - <literal>FOO"BAR"BAZ</> is interpreted as <literal>fooBARbaz</>, - and <literal>"A weird"" name"</> becomes <literal>A weird" - name</>. + <literal>FOO"BAR"BAZ</literal> is interpreted as <literal>fooBARbaz</literal>, + and <literal>"A weird"" name"</literal> becomes <literal>A weird" + name</literal>. </para> <para> @@ -834,7 +834,7 @@ testdb=> </para> <para> - Many of the meta-commands act on the <firstterm>current query buffer</>. + Many of the meta-commands act on the <firstterm>current query buffer</firstterm>. This is simply a buffer holding whatever SQL command text has been typed but not yet sent to the server for execution. This will include previous input lines as well as any text appearing before the meta-command on the @@ -861,9 +861,9 @@ testdb=> <term><literal>\c</literal> or <literal>\connect [ -reuse-previous=<replaceable class="parameter">on|off</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">host</replaceable> ] [ <replaceable class="parameter">port</replaceable> ] | <replaceable class="parameter">conninfo</replaceable> ]</literal></term> <listitem> <para> - Establishes a new connection to a <productname>PostgreSQL</> + Establishes a new connection to a <productname>PostgreSQL</productname> server. The connection parameters to use can be specified either - using a positional syntax, or using <replaceable>conninfo</> connection + using a positional syntax, or using <replaceable>conninfo</replaceable> connection strings as detailed in <xref linkend="libpq-connstring">. </para> @@ -871,8 +871,8 @@ testdb=> Where the command omits database name, user, host, or port, the new connection can reuse values from the previous connection. By default, values from the previous connection are reused except when processing - a <replaceable>conninfo</> string. Passing a first argument - of <literal>-reuse-previous=on</> + a <replaceable>conninfo</replaceable> string. Passing a first argument + of <literal>-reuse-previous=on</literal> or <literal>-reuse-previous=off</literal> overrides that default. When the command neither specifies nor reuses a particular parameter, the <application>libpq</application> default is used. Specifying any @@ -969,7 +969,7 @@ testdb=> </para> <para> - When <literal>program</> is specified, + When <literal>program</literal> is specified, <replaceable class="parameter">command</replaceable> is executed by <application>psql</application> and the data passed from or to <replaceable class="parameter">command</replaceable> is @@ -980,17 +980,17 @@ testdb=> </para> <para> - For <literal>\copy ... from stdin</>, data rows are read from the same + For <literal>\copy ... from stdin</literal>, data rows are read from the same source that issued the command, continuing until <literal>\.</literal> - is read or the stream reaches <acronym>EOF</>. This option is useful + is read or the stream reaches <acronym>EOF</acronym>. This option is useful for populating tables in-line within a SQL script file. - For <literal>\copy ... to stdout</>, output is sent to the same place - as <application>psql</> command output, and - the <literal>COPY <replaceable>count</></literal> command status is + For <literal>\copy ... to stdout</literal>, output is sent to the same place + as <application>psql</application> command output, and + the <literal>COPY <replaceable>count</replaceable></literal> command status is not printed (since it might be confused with a data row). To read/write <application>psql</application>'s standard input or - output regardless of the current command source or <literal>\o</> - option, write <literal>from pstdin</> or <literal>to pstdout</>. + output regardless of the current command source or <literal>\o</literal> + option, write <literal>from pstdin</literal> or <literal>to pstdout</literal>. </para> <para> @@ -998,9 +998,9 @@ testdb=> <acronym>SQL</acronym> <xref linkend="sql-copy"> command. All options other than the data source/destination are as specified for <xref linkend="sql-copy">. - Because of this, special parsing rules apply to the <command>\copy</> + Because of this, special parsing rules apply to the <command>\copy</command> meta-command. Unlike most other meta-commands, the entire remainder - of the line is always taken to be the arguments of <command>\copy</>, + of the line is always taken to be the arguments of <command>\copy</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. </para> @@ -1040,7 +1040,7 @@ testdb=> Executes the current query buffer (like <literal>\g</literal>) and shows the results in a crosstab grid. The query must return at least three columns. - The output column identified by <replaceable class="parameter">colV</> + The output column identified by <replaceable class="parameter">colV</replaceable> becomes a vertical header and the output column identified by <replaceable class="parameter">colH</replaceable> becomes a horizontal header. @@ -1068,7 +1068,7 @@ testdb=> <para> The vertical header, displayed as the leftmost column, contains the - values found in column <replaceable class="parameter">colV</>, in the + values found in column <replaceable class="parameter">colV</replaceable>, in the same order as in the query results, but with duplicates removed. </para> @@ -1077,11 +1077,11 @@ testdb=> found in column <replaceable class="parameter">colH</replaceable>, with duplicates removed. By default, these appear in the same order as in the query results. But if the - optional <replaceable class="parameter">sortcolH</> argument is given, + optional <replaceable class="parameter">sortcolH</replaceable> argument is given, it identifies a column whose values must be integer numbers, and the values from <replaceable class="parameter">colH</replaceable> will appear in the horizontal header sorted according to the - corresponding <replaceable class="parameter">sortcolH</> values. + corresponding <replaceable class="parameter">sortcolH</replaceable> values. </para> <para> @@ -1094,7 +1094,7 @@ testdb=> the value of <replaceable class="parameter">colH</replaceable> is <literal>x</literal> and the value of <replaceable class="parameter">colV</replaceable> - is <literal>y</>. If there is no such row, the cell is empty. If + is <literal>y</literal>. If there is no such row, the cell is empty. If there are multiple such rows, an error is reported. </para> </listitem> @@ -1115,13 +1115,13 @@ testdb=> Associated indexes, constraints, rules, and triggers are also shown. For foreign tables, the associated foreign server is shown as well. - (<quote>Matching the pattern</> is defined in + (<quote>Matching the pattern</quote> is defined in <xref linkend="APP-PSQL-patterns" endterm="APP-PSQL-patterns-title"> below.) </para> <para> - For some types of relation, <literal>\d</> shows additional information + For some types of relation, <literal>\d</literal> shows additional information for each column: column values for sequences, indexed expressions for indexes, and foreign data wrapper options for foreign tables. </para> @@ -1237,9 +1237,9 @@ testdb=> <term><literal>\dd[S] [ <link linkend="APP-PSQL-patterns"><replaceable class="parameter">pattern</replaceable></link> ]</literal></term> <listitem> <para> - Shows the descriptions of objects of type <literal>constraint</>, - <literal>operator class</>, <literal>operator family</>, - <literal>rule</>, and <literal>trigger</>. All + Shows the descriptions of objects of type <literal>constraint</literal>, + <literal>operator class</literal>, <literal>operator family</literal>, + <literal>rule</literal>, and <literal>trigger</literal>. All other comments may be viewed by the respective backslash commands for those object types. </para> @@ -1318,7 +1318,7 @@ testdb=> respectively. You can specify any or all of these letters, in any order, to obtain a listing of objects - of these types. For example, <literal>\dit</> lists indexes + of these types. For example, <literal>\dit</literal> lists indexes and tables. If <literal>+</literal> is appended to the command name, each object is listed with its physical size on disk and its associated description, if any. @@ -1408,11 +1408,11 @@ testdb=> <listitem> <para> Lists functions, together with their result data types, argument data - types, and function types, which are classified as <quote>agg</> - (aggregate), <quote>normal</>, <quote>trigger</>, or <quote>window</>. + types, and function types, which are classified as <quote>agg</quote> + (aggregate), <quote>normal</quote>, <quote>trigger</quote>, or <quote>window</quote>. To display only functions - of specific type(s), add the corresponding letters <literal>a</>, - <literal>n</>, <literal>t</>, or <literal>w</> to the command. + of specific type(s), add the corresponding letters <literal>a</literal>, + <literal>n</literal>, <literal>t</literal>, or <literal>w</literal> to the command. If <replaceable class="parameter">pattern</replaceable> is specified, only functions whose names match the pattern are shown. @@ -1429,7 +1429,7 @@ testdb=> <para> To look up functions taking arguments or returning values of a specific data type, use your pager's search capability to scroll through the - <literal>\df</> output. + <literal>\df</literal> output. </para> </tip> @@ -1497,8 +1497,8 @@ testdb=> <listitem> <para> Lists database roles. - (Since the concepts of <quote>users</> and <quote>groups</> have been - unified into <quote>roles</>, this command is now equivalent to + (Since the concepts of <quote>users</quote> and <quote>groups</quote> have been + unified into <quote>roles</quote>, this command is now equivalent to <literal>\du</literal>.) By default, only user-created roles are shown; supply the <literal>S</literal> modifier to include system roles. @@ -1624,7 +1624,7 @@ testdb=> <replaceable>role-pattern</replaceable> and <replaceable>database-pattern</replaceable> are used to select specific roles and databases to list, respectively. If omitted, or if - <literal>*</> is specified, all settings are listed, including those + <literal>*</literal> is specified, all settings are listed, including those not role-specific or database-specific, respectively. </para> @@ -1674,7 +1674,7 @@ testdb=> specified, only types whose names match the pattern are listed. If <literal>+</literal> is appended to the command name, each type is listed with its internal name and size, its allowed values - if it is an <type>enum</> type, and its associated permissions. + if it is an <type>enum</type> type, and its associated permissions. By default, only user-created objects are shown; supply a pattern or the <literal>S</literal> modifier to include system objects. @@ -1687,8 +1687,8 @@ testdb=> <listitem> <para> Lists database roles. - (Since the concepts of <quote>users</> and <quote>groups</> have been - unified into <quote>roles</>, this command is now equivalent to + (Since the concepts of <quote>users</quote> and <quote>groups</quote> have been + unified into <quote>roles</quote>, this command is now equivalent to <literal>\dg</literal>.) By default, only user-created roles are shown; supply the <literal>S</literal> modifier to include system roles. @@ -1730,7 +1730,7 @@ testdb=> </varlistentry> <varlistentry> - <term><literal>\e</literal> or <literal>\edit</> <literal> <optional> <replaceable class="parameter">filename</> </optional> <optional> <replaceable class="parameter">line_number</> </optional> </literal></term> + <term><literal>\e</literal> or <literal>\edit</literal> <literal> <optional> <replaceable class="parameter">filename</replaceable> </optional> <optional> <replaceable class="parameter">line_number</replaceable> </optional> </literal></term> <listitem> <para> @@ -1750,8 +1750,8 @@ testdb=> whole buffer as a single line. Any complete queries are immediately executed; that is, if the query buffer contains or ends with a semicolon, everything up to that point is executed. Whatever remains - will wait in the query buffer; type semicolon or <literal>\g</> to - send it, or <literal>\r</> to cancel it by clearing the query buffer. + will wait in the query buffer; type semicolon or <literal>\g</literal> to + send it, or <literal>\r</literal> to cancel it by clearing the query buffer. Treating the buffer as a single line primarily affects meta-commands: whatever is in the buffer after a meta-command will be taken as argument(s) to the meta-command, even if it spans multiple lines. @@ -1803,27 +1803,27 @@ Tue Oct 26 21:40:57 CEST 1999 </varlistentry> <varlistentry> - <term><literal>\ef <optional> <replaceable class="parameter">function_description</> <optional> <replaceable class="parameter">line_number</> </optional> </optional> </literal></term> + <term><literal>\ef <optional> <replaceable class="parameter">function_description</replaceable> <optional> <replaceable class="parameter">line_number</replaceable> </optional> </optional> </literal></term> <listitem> <para> This command fetches and edits the definition of the named function, - in the form of a <command>CREATE OR REPLACE FUNCTION</> command. - Editing is done in the same way as for <literal>\edit</>. + in the form of a <command>CREATE OR REPLACE FUNCTION</command> command. + Editing is done in the same way as for <literal>\edit</literal>. After the editor exits, the updated command waits in the query buffer; - type semicolon or <literal>\g</> to send it, or <literal>\r</> + type semicolon or <literal>\g</literal> to send it, or <literal>\r</literal> to cancel. </para> <para> The target function can be specified by name alone, or by name - and arguments, for example <literal>foo(integer, text)</>. + and arguments, for example <literal>foo(integer, text)</literal>. The argument types must be given if there is more than one function of the same name. </para> <para> - If no function is specified, a blank <command>CREATE FUNCTION</> + If no function is specified, a blank <command>CREATE FUNCTION</command> template is presented for editing. </para> @@ -1836,7 +1836,7 @@ Tue Oct 26 21:40:57 CEST 1999 <para> Unlike most other meta-commands, the entire remainder of the line is - always taken to be the argument(s) of <command>\ef</>, and neither + always taken to be the argument(s) of <command>\ef</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. </para> @@ -1871,28 +1871,28 @@ Tue Oct 26 21:40:57 CEST 1999 <para> Repeats the most recent server error message at maximum verbosity, as though <varname>VERBOSITY</varname> were set - to <literal>verbose</> and <varname>SHOW_CONTEXT</varname> were - set to <literal>always</>. + to <literal>verbose</literal> and <varname>SHOW_CONTEXT</varname> were + set to <literal>always</literal>. </para> </listitem> </varlistentry> <varlistentry> - <term><literal>\ev <optional> <replaceable class="parameter">view_name</> <optional> <replaceable class="parameter">line_number</> </optional> </optional> </literal></term> + <term><literal>\ev <optional> <replaceable class="parameter">view_name</replaceable> <optional> <replaceable class="parameter">line_number</replaceable> </optional> </optional> </literal></term> <listitem> <para> This command fetches and edits the definition of the named view, - in the form of a <command>CREATE OR REPLACE VIEW</> command. - Editing is done in the same way as for <literal>\edit</>. + in the form of a <command>CREATE OR REPLACE VIEW</command> command. + Editing is done in the same way as for <literal>\edit</literal>. After the editor exits, the updated command waits in the query buffer; - type semicolon or <literal>\g</> to send it, or <literal>\r</> + type semicolon or <literal>\g</literal> to send it, or <literal>\r</literal> to cancel. </para> <para> - If no view is specified, a blank <command>CREATE VIEW</> + If no view is specified, a blank <command>CREATE VIEW</command> template is presented for editing. </para> @@ -1903,7 +1903,7 @@ Tue Oct 26 21:40:57 CEST 1999 <para> Unlike most other meta-commands, the entire remainder of the line is - always taken to be the argument(s) of <command>\ev</>, and neither + always taken to be the argument(s) of <command>\ev</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. </para> @@ -1944,7 +1944,7 @@ Tue Oct 26 21:40:57 CEST 1999 alternative to the <command>\o</command> command. </para> <para> - If the argument begins with <literal>|</>, then the entire remainder + If the argument begins with <literal>|</literal>, then the entire remainder of the line is taken to be the <replaceable class="parameter">command</replaceable> to execute, and neither variable interpolation nor backquote expansion are @@ -1982,13 +1982,13 @@ Tue Oct 26 21:40:57 CEST 1999 Sends the current query buffer to the server, then treats each column of each row of the query's output (if any) as a SQL statement to be executed. For example, to create an index on each - column of <structname>my_table</>: + column of <structname>my_table</structname>: <programlisting> -=> <userinput>SELECT format('create index on my_table(%I)', attname)</> --> <userinput>FROM pg_attribute</> --> <userinput>WHERE attrelid = 'my_table'::regclass AND attnum > 0</> --> <userinput>ORDER BY attnum</> --> <userinput>\gexec</> +=> <userinput>SELECT format('create index on my_table(%I)', attname)</userinput> +-> <userinput>FROM pg_attribute</userinput> +-> <userinput>WHERE attrelid = 'my_table'::regclass AND attnum > 0</userinput> +-> <userinput>ORDER BY attnum</userinput> +-> <userinput>\gexec</userinput> CREATE INDEX CREATE INDEX CREATE INDEX @@ -2001,14 +2001,14 @@ CREATE INDEX are returned, and left-to-right within each row if there is more than one column. NULL fields are ignored. The generated queries are sent literally to the server for processing, so they cannot be - <application>psql</> meta-commands nor contain <application>psql</> + <application>psql</application> meta-commands nor contain <application>psql</application> variable references. If any individual query fails, execution of the remaining queries continues unless <varname>ON_ERROR_STOP</varname> is set. Execution of each query is subject to <varname>ECHO</varname> processing. (Setting <varname>ECHO</varname> to <literal>all</literal> or <literal>queries</literal> is often advisable when - using <command>\gexec</>.) Query logging, single-step mode, + using <command>\gexec</command>.) Query logging, single-step mode, timing, and other query execution features apply to each generated query as well. </para> @@ -2026,7 +2026,7 @@ CREATE INDEX <listitem> <para> Sends the current query buffer to the server and stores the - query's output into <application>psql</> variables (see <xref + query's output into <application>psql</application> variables (see <xref linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title">). The query to be executed must return exactly one row. Each column of the row is stored into a separate variable, named the same as the @@ -2092,7 +2092,7 @@ hello 10 <para> Unlike most other meta-commands, the entire remainder of the line is - always taken to be the argument(s) of <command>\help</>, and neither + always taken to be the argument(s) of <command>\help</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. </para> @@ -2133,7 +2133,7 @@ hello 10 <para> If <replaceable>filename</replaceable> is <literal>-</literal> (hyphen), then standard input is read until an EOF indication - or <command>\q</> meta-command. This can be used to intersperse + or <command>\q</command> meta-command. This can be used to intersperse interactive input with input from files. Note that Readline behavior will be used only if it is active at the outermost level. </para> @@ -2208,7 +2208,7 @@ hello 10 the same source file. If EOF is reached on the main input file or an <command>\include</command>-ed file before all local <command>\if</command>-blocks have been closed, - then <application>psql</> will raise an error. + then <application>psql</application> will raise an error. </para> <para> Here is an example: @@ -2241,7 +2241,7 @@ SELECT <term><literal>\ir</literal> or <literal>\include_relative</literal> <replaceable class="parameter">filename</replaceable></term> <listitem> <para> - The <literal>\ir</> command is similar to <literal>\i</>, but resolves + The <literal>\ir</literal> command is similar to <literal>\i</literal>, but resolves relative file names differently. When executing in interactive mode, the two commands behave identically. However, when invoked from a script, <literal>\ir</literal> interprets file names relative to the @@ -2366,7 +2366,7 @@ lo_import 152801 </para> <para> - If the argument begins with <literal>|</>, then the entire remainder + If the argument begins with <literal>|</literal>, then the entire remainder of the line is taken to be the <replaceable class="parameter">command</replaceable> to execute, and neither variable interpolation nor backquote expansion are @@ -2409,7 +2409,7 @@ lo_import 152801 <para> Changes the password of the specified user (by default, the current user). This command prompts for the new password, encrypts it, and - sends it to the server as an <command>ALTER ROLE</> command. This + sends it to the server as an <command>ALTER ROLE</command> command. This makes sure that the new password does not appear in cleartext in the command history, the server log, or elsewhere. </para> @@ -2421,16 +2421,16 @@ lo_import 152801 <listitem> <para> Prompts the user to supply text, which is assigned to the variable - <replaceable class="parameter">name</>. + <replaceable class="parameter">name</replaceable>. An optional prompt string, <replaceable - class="parameter">text</>, can be specified. (For multiword + class="parameter">text</replaceable>, can be specified. (For multiword prompts, surround the text with single quotes.) </para> <para> - By default, <literal>\prompt</> uses the terminal for input and - output. However, if the <option>-f</> command line switch was - used, <literal>\prompt</> uses standard input and standard output. + By default, <literal>\prompt</literal> uses the terminal for input and + output. However, if the <option>-f</option> command line switch was + used, <literal>\prompt</literal> uses standard input and standard output. </para> </listitem> </varlistentry> @@ -2484,16 +2484,16 @@ lo_import 152801 <term><literal>columns</literal></term> <listitem> <para> - Sets the target width for the <literal>wrapped</> format, and also + Sets the target width for the <literal>wrapped</literal> format, and also the width limit for determining whether output is wide enough to require the pager or switch to the vertical display in expanded auto mode. Zero (the default) causes the target width to be controlled by the - environment variable <envar>COLUMNS</>, or the detected screen width - if <envar>COLUMNS</> is not set. - In addition, if <literal>columns</> is zero then the - <literal>wrapped</> format only affects screen output. - If <literal>columns</> is nonzero then file and pipe output is + environment variable <envar>COLUMNS</envar>, or the detected screen width + if <envar>COLUMNS</envar> is not set. + In addition, if <literal>columns</literal> is zero then the + <literal>wrapped</literal> format only affects screen output. + If <literal>columns</literal> is nonzero then file and pipe output is wrapped to that width as well. </para> </listitem> @@ -2552,7 +2552,7 @@ lo_import 152801 If <replaceable class="parameter">value</replaceable> is specified it must be either <literal>on</literal> or <literal>off</literal> which will enable or disable display of the table footer - (the <literal>(<replaceable>n</> rows)</literal> count). + (the <literal>(<replaceable>n</replaceable> rows)</literal> count). If <replaceable class="parameter">value</replaceable> is omitted the command toggles footer display on or off. </para> @@ -2573,7 +2573,7 @@ lo_import 152801 is enough.) </para> - <para><literal>unaligned</> format writes all columns of a row on one + <para><literal>unaligned</literal> format writes all columns of a row on one line, separated by the currently active field separator. This is useful for creating output that might be intended to be read in by other programs (for example, tab-separated or comma-separated @@ -2584,18 +2584,18 @@ lo_import 152801 nicely formatted text output; this is the default. </para> - <para><literal>wrapped</> format is like <literal>aligned</> but wraps + <para><literal>wrapped</literal> format is like <literal>aligned</literal> but wraps wide data values across lines to make the output fit in the target column width. The target width is determined as described under - the <literal>columns</> option. Note that <application>psql</> will + the <literal>columns</literal> option. Note that <application>psql</application> will not attempt to wrap column header titles; therefore, - <literal>wrapped</> format behaves the same as <literal>aligned</> + <literal>wrapped</literal> format behaves the same as <literal>aligned</literal> if the total width needed for column headers exceeds the target. </para> <para> - The <literal>html</>, <literal>asciidoc</>, <literal>latex</>, - <literal>latex-longtable</literal>, and <literal>troff-ms</> + The <literal>html</literal>, <literal>asciidoc</literal>, <literal>latex</literal>, + <literal>latex-longtable</literal>, and <literal>troff-ms</literal> formats put out tables that are intended to be included in documents using the respective mark-up language. They are not complete documents! This might not be @@ -2603,7 +2603,7 @@ lo_import 152801 <application>LaTeX</application> you must have a complete document wrapper. <literal>latex-longtable</literal> also requires the <application>LaTeX</application> - <literal>longtable</literal> and <literal>booktabs</> packages. + <literal>longtable</literal> and <literal>booktabs</literal> packages. </para> </listitem> </varlistentry> @@ -2617,9 +2617,9 @@ lo_import 152801 or <literal>unicode</literal>. Unique abbreviations are allowed. (That would mean one letter is enough.) - The default setting is <literal>ascii</>. - This option only affects the <literal>aligned</> and - <literal>wrapped</> output formats. + The default setting is <literal>ascii</literal>. + This option only affects the <literal>aligned</literal> and + <literal>wrapped</literal> output formats. </para> <para><literal>ascii</literal> style uses plain <acronym>ASCII</acronym> @@ -2627,17 +2627,17 @@ lo_import 152801 a <literal>+</literal> symbol in the right-hand margin. When the <literal>wrapped</literal> format wraps data from one line to the next without a newline character, a dot - (<literal>.</>) is shown in the right-hand margin of the first line, + (<literal>.</literal>) is shown in the right-hand margin of the first line, and again in the left-hand margin of the following line. </para> - <para><literal>old-ascii</literal> style uses plain <acronym>ASCII</> + <para><literal>old-ascii</literal> style uses plain <acronym>ASCII</acronym> characters, using the formatting style used in <productname>PostgreSQL</productname> 8.4 and earlier. Newlines in data are shown using a <literal>:</literal> symbol in place of the left-hand column separator. When the data is wrapped from one line - to the next without a newline character, a <literal>;</> + to the next without a newline character, a <literal>;</literal> symbol is used in place of the left-hand column separator. </para> @@ -2650,7 +2650,7 @@ lo_import 152801 </para> <para> - When the <literal>border</> setting is greater than zero, + When the <literal>border</literal> setting is greater than zero, the <literal>linestyle</literal> option also determines the characters with which the border lines are drawn. Plain <acronym>ASCII</acronym> characters work everywhere, but @@ -2689,7 +2689,7 @@ lo_import 152801 <term><literal>pager</literal></term> <listitem> <para> - Controls use of a pager program for query and <application>psql</> + Controls use of a pager program for query and <application>psql</application> help output. If the environment variable <envar>PSQL_PAGER</envar> or <envar>PAGER</envar> is set, the output is piped to the specified program. Otherwise a platform-dependent default program @@ -2697,13 +2697,13 @@ lo_import 152801 </para> <para> - When the <literal>pager</> option is <literal>off</>, the pager - program is not used. When the <literal>pager</> option is - <literal>on</>, the pager is used when appropriate, i.e., when the + When the <literal>pager</literal> option is <literal>off</literal>, the pager + program is not used. When the <literal>pager</literal> option is + <literal>on</literal>, the pager is used when appropriate, i.e., when the output is to a terminal and will not fit on the screen. - The <literal>pager</> option can also be set to <literal>always</>, + The <literal>pager</literal> option can also be set to <literal>always</literal>, which causes the pager to be used for all terminal output regardless - of whether it fits on the screen. <literal>\pset pager</> + of whether it fits on the screen. <literal>\pset pager</literal> without a <replaceable class="parameter">value</replaceable> toggles pager use on and off. </para> @@ -2714,7 +2714,7 @@ lo_import 152801 <term><literal>pager_min_lines</literal></term> <listitem> <para> - If <literal>pager_min_lines</> is set to a number greater than the + If <literal>pager_min_lines</literal> is set to a number greater than the page height, the pager program will not be called unless there are at least this many lines of output to show. The default setting is 0. @@ -2760,7 +2760,7 @@ lo_import 152801 In <literal>latex-longtable</literal> format, this controls the proportional width of each column containing a left-aligned data type. It is specified as a whitespace-separated list of values, - e.g. <literal>'0.2 0.2 0.6'</>. Unspecified output columns + e.g. <literal>'0.2 0.2 0.6'</literal>. Unspecified output columns use the last specified value. </para> </listitem> @@ -2902,7 +2902,7 @@ lo_import 152801 <listitem> <para> - Sets the <application>psql</> variable <replaceable + Sets the <application>psql</application> variable <replaceable class="parameter">name</replaceable> to <replaceable class="parameter">value</replaceable>, or if more than one value is given, to the concatenation of all of them. If only one @@ -2910,8 +2910,8 @@ lo_import 152801 unset a variable, use the <command>\unset</command> command. </para> - <para><command>\set</> without any arguments displays the names and values - of all currently-set <application>psql</> variables. + <para><command>\set</command> without any arguments displays the names and values + of all currently-set <application>psql</application> variables. </para> <para> @@ -2958,19 +2958,19 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> </varlistentry> <varlistentry> - <term><literal>\sf[+] <replaceable class="parameter">function_description</> </literal></term> + <term><literal>\sf[+] <replaceable class="parameter">function_description</replaceable> </literal></term> <listitem> <para> This command fetches and shows the definition of the named function, - in the form of a <command>CREATE OR REPLACE FUNCTION</> command. + in the form of a <command>CREATE OR REPLACE FUNCTION</command> command. The definition is printed to the current query output channel, as set by <command>\o</command>. </para> <para> The target function can be specified by name alone, or by name - and arguments, for example <literal>foo(integer, text)</>. + and arguments, for example <literal>foo(integer, text)</literal>. The argument types must be given if there is more than one function of the same name. </para> @@ -2983,7 +2983,7 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <para> Unlike most other meta-commands, the entire remainder of the line is - always taken to be the argument(s) of <command>\sf</>, and neither + always taken to be the argument(s) of <command>\sf</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. </para> @@ -2992,12 +2992,12 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <varlistentry> - <term><literal>\sv[+] <replaceable class="parameter">view_name</> </literal></term> + <term><literal>\sv[+] <replaceable class="parameter">view_name</replaceable> </literal></term> <listitem> <para> This command fetches and shows the definition of the named view, - in the form of a <command>CREATE OR REPLACE VIEW</> command. + in the form of a <command>CREATE OR REPLACE VIEW</command> command. The definition is printed to the current query output channel, as set by <command>\o</command>. </para> @@ -3009,7 +3009,7 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <para> Unlike most other meta-commands, the entire remainder of the line is - always taken to be the argument(s) of <command>\sv</>, and neither + always taken to be the argument(s) of <command>\sv</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. </para> @@ -3062,13 +3062,13 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <listitem> <para> - Unsets (deletes) the <application>psql</> variable <replaceable + Unsets (deletes) the <application>psql</application> variable <replaceable class="parameter">name</replaceable>. </para> <para> Most variables that control <application>psql</application>'s behavior - cannot be unset; instead, an <literal>\unset</> command is interpreted + cannot be unset; instead, an <literal>\unset</literal> command is interpreted as setting them to their default values. See <xref linkend="APP-PSQL-variables" endterm="APP-PSQL-variables-title">, below. @@ -3079,7 +3079,7 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <varlistentry> <term><literal>\w</literal> or <literal>\write</literal> <replaceable class="parameter">filename</replaceable></term> - <term><literal>\w</literal> or <literal>\write</literal> <literal>|</><replaceable class="parameter">command</replaceable></term> + <term><literal>\w</literal> or <literal>\write</literal> <literal>|</literal><replaceable class="parameter">command</replaceable></term> <listitem> <para> Writes the current query buffer to the file <replaceable @@ -3090,7 +3090,7 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> </para> <para> - If the argument begins with <literal>|</>, then the entire remainder + If the argument begins with <literal>|</literal>, then the entire remainder of the line is taken to be the <replaceable class="parameter">command</replaceable> to execute, and neither variable interpolation nor backquote expansion are @@ -3105,10 +3105,10 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <term><literal>\watch [ <replaceable class="parameter">seconds</replaceable> ]</literal></term> <listitem> <para> - Repeatedly execute the current query buffer (as <literal>\g</> does) + Repeatedly execute the current query buffer (as <literal>\g</literal> does) until interrupted or the query fails. Wait the specified number of seconds (default 2) between executions. Each query result is - displayed with a header that includes the <literal>\pset title</> + displayed with a header that includes the <literal>\pset title</literal> string (if any), the time as of query start, and the delay interval. </para> <para> @@ -3153,14 +3153,14 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <term><literal>\! [ <replaceable class="parameter">command</replaceable> ]</literal></term> <listitem> <para> - With no argument, escapes to a sub-shell; <application>psql</> + With no argument, escapes to a sub-shell; <application>psql</application> resumes when the sub-shell exits. With an argument, executes the shell command <replaceable class="parameter">command</replaceable>. </para> <para> Unlike most other meta-commands, the entire remainder of the line is - always taken to be the argument(s) of <command>\!</>, and neither + always taken to be the argument(s) of <command>\!</command>, and neither variable interpolation nor backquote expansion are performed in the arguments. The rest of the line is simply passed literally to the shell. @@ -3170,16 +3170,16 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> <varlistentry> - <term><literal>\? [ <replaceable class="parameter">topic</> ]</literal></term> + <term><literal>\? [ <replaceable class="parameter">topic</replaceable> ]</literal></term> <listitem> <para> Shows help information. The optional - <replaceable class="parameter">topic</> parameter - (defaulting to <literal>commands</>) selects which part of <application>psql</application> is - explained: <literal>commands</> describes <application>psql</>'s - backslash commands; <literal>options</> describes the command-line - options that can be passed to <application>psql</>; - and <literal>variables</> shows help about <application>psql</application> configuration + <replaceable class="parameter">topic</replaceable> parameter + (defaulting to <literal>commands</literal>) selects which part of <application>psql</application> is + explained: <literal>commands</literal> describes <application>psql</application>'s + backslash commands; <literal>options</literal> describes the command-line + options that can be passed to <application>psql</application>; + and <literal>variables</literal> shows help about <application>psql</application> configuration variables. </para> </listitem> @@ -3196,7 +3196,7 @@ testdb=> <userinput>\setenv LESS -imx4F</userinput> </para> <para> - Normally, <application>psql</> will dispatch a SQL command to the + Normally, <application>psql</application> will dispatch a SQL command to the server as soon as it reaches the command-ending semicolon, even if more input remains on the current line. Thus for example entering <programlisting> @@ -3205,7 +3205,7 @@ select 1; select 2; select 3; will result in the three SQL commands being individually sent to the server, with each one's results being displayed before continuing to the next command. However, a semicolon entered - as <literal>\;</> will not trigger command processing, so that the + as <literal>\;</literal> will not trigger command processing, so that the command before it and the one after are effectively combined and sent to the server in one request. So for example <programlisting> @@ -3214,14 +3214,14 @@ select 1\; select 2\; select 3; results in sending the three SQL commands to the server in a single request, when the non-backslashed semicolon is reached. The server executes such a request as a single transaction, - unless there are explicit <command>BEGIN</>/<command>COMMIT</> + unless there are explicit <command>BEGIN</command>/<command>COMMIT</command> commands included in the string to divide it into multiple transactions. (See <xref linkend="protocol-flow-multi-statement"> for more details about how the server handles multi-query strings.) <application>psql</application> prints only the last query result it receives for each request; in this example, although all - three <command>SELECT</>s are indeed executed, <application>psql</> - only prints the <literal>3</>. + three <command>SELECT</command>s are indeed executed, <application>psql</application> + only prints the <literal>3</literal>. </para> </listitem> </varlistentry> @@ -3238,54 +3238,54 @@ select 1\; select 2\; select 3; </indexterm> <para> - The various <literal>\d</> commands accept a <replaceable + The various <literal>\d</literal> commands accept a <replaceable class="parameter">pattern</replaceable> parameter to specify the object name(s) to be displayed. In the simplest case, a pattern is just the exact name of the object. The characters within a pattern are normally folded to lower case, just as in SQL names; - for example, <literal>\dt FOO</> will display the table named - <literal>foo</>. As in SQL names, placing double quotes around + for example, <literal>\dt FOO</literal> will display the table named + <literal>foo</literal>. As in SQL names, placing double quotes around a pattern stops folding to lower case. Should you need to include an actual double quote character in a pattern, write it as a pair of double quotes within a double-quote sequence; again this is in accord with the rules for SQL quoted identifiers. For example, - <literal>\dt "FOO""BAR"</> will display the table named - <literal>FOO"BAR</> (not <literal>foo"bar</>). Unlike the normal + <literal>\dt "FOO""BAR"</literal> will display the table named + <literal>FOO"BAR</literal> (not <literal>foo"bar</literal>). Unlike the normal rules for SQL names, you can put double quotes around just part - of a pattern, for instance <literal>\dt FOO"FOO"BAR</> will display - the table named <literal>fooFOObar</>. + of a pattern, for instance <literal>\dt FOO"FOO"BAR</literal> will display + the table named <literal>fooFOObar</literal>. </para> <para> Whenever the <replaceable class="parameter">pattern</replaceable> parameter - is omitted completely, the <literal>\d</> commands display all objects + is omitted completely, the <literal>\d</literal> commands display all objects that are visible in the current schema search path — this is - equivalent to using <literal>*</> as the pattern. - (An object is said to be <firstterm>visible</> if its + equivalent to using <literal>*</literal> as the pattern. + (An object is said to be <firstterm>visible</firstterm> if its containing schema is in the search path and no object of the same kind and name appears earlier in the search path. This is equivalent to the statement that the object can be referenced by name without explicit schema qualification.) To see all objects in the database regardless of visibility, - use <literal>*.*</> as the pattern. + use <literal>*.*</literal> as the pattern. </para> <para> - Within a pattern, <literal>*</> matches any sequence of characters - (including no characters) and <literal>?</> matches any single character. + Within a pattern, <literal>*</literal> matches any sequence of characters + (including no characters) and <literal>?</literal> matches any single character. (This notation is comparable to Unix shell file name patterns.) - For example, <literal>\dt int*</> displays tables whose names - begin with <literal>int</>. But within double quotes, <literal>*</> - and <literal>?</> lose these special meanings and are just matched + For example, <literal>\dt int*</literal> displays tables whose names + begin with <literal>int</literal>. But within double quotes, <literal>*</literal> + and <literal>?</literal> lose these special meanings and are just matched literally. </para> <para> - A pattern that contains a dot (<literal>.</>) is interpreted as a schema + A pattern that contains a dot (<literal>.</literal>) is interpreted as a schema name pattern followed by an object name pattern. For example, - <literal>\dt foo*.*bar*</> displays all tables whose table name - includes <literal>bar</> that are in schemas whose schema name - starts with <literal>foo</>. When no dot appears, then the pattern + <literal>\dt foo*.*bar*</literal> displays all tables whose table name + includes <literal>bar</literal> that are in schemas whose schema name + starts with <literal>foo</literal>. When no dot appears, then the pattern matches only objects that are visible in the current schema search path. Again, a dot within double quotes loses its special meaning and is matched literally. @@ -3293,28 +3293,28 @@ select 1\; select 2\; select 3; <para> Advanced users can use regular-expression notations such as character - classes, for example <literal>[0-9]</> to match any digit. All regular + classes, for example <literal>[0-9]</literal> to match any digit. All regular expression special characters work as specified in - <xref linkend="functions-posix-regexp">, except for <literal>.</> which - is taken as a separator as mentioned above, <literal>*</> which is - translated to the regular-expression notation <literal>.*</>, - <literal>?</> which is translated to <literal>.</>, and - <literal>$</> which is matched literally. You can emulate + <xref linkend="functions-posix-regexp">, except for <literal>.</literal> which + is taken as a separator as mentioned above, <literal>*</literal> which is + translated to the regular-expression notation <literal>.*</literal>, + <literal>?</literal> which is translated to <literal>.</literal>, and + <literal>$</literal> which is matched literally. You can emulate these pattern characters at need by writing - <literal>?</> for <literal>.</>, + <literal>?</literal> for <literal>.</literal>, <literal>(<replaceable class="parameter">R</replaceable>+|)</literal> for <literal><replaceable class="parameter">R</replaceable>*</literal>, or <literal>(<replaceable class="parameter">R</replaceable>|)</literal> for <literal><replaceable class="parameter">R</replaceable>?</literal>. - <literal>$</> is not needed as a regular-expression character since + <literal>$</literal> is not needed as a regular-expression character since the pattern must match the whole name, unlike the usual - interpretation of regular expressions (in other words, <literal>$</> - is automatically appended to your pattern). Write <literal>*</> at the + interpretation of regular expressions (in other words, <literal>$</literal> + is automatically appended to your pattern). Write <literal>*</literal> at the beginning and/or end if you don't wish the pattern to be anchored. Note that within double quotes, all regular expression special characters lose their special meanings and are matched literally. Also, the regular expression special characters are matched literally in operator name - patterns (i.e., the argument of <literal>\do</>). + patterns (i.e., the argument of <literal>\do</literal>). </para> </refsect3> </refsect2> @@ -3387,14 +3387,14 @@ bar <para> Variables that control <application>psql</application>'s behavior - generally cannot be unset or set to invalid values. An <literal>\unset</> + generally cannot be unset or set to invalid values. An <literal>\unset</literal> command is allowed but is interpreted as setting the variable to its - default value. A <literal>\set</> command without a second argument is - interpreted as setting the variable to <literal>on</>, for control + default value. A <literal>\set</literal> command without a second argument is + interpreted as setting the variable to <literal>on</literal>, for control variables that accept that value, and is rejected for others. Also, - control variables that accept the values <literal>on</> - and <literal>off</> will also accept other common spellings of Boolean - values, such as <literal>true</> and <literal>false</>. + control variables that accept the values <literal>on</literal> + and <literal>off</literal> will also accept other common spellings of Boolean + values, such as <literal>true</literal> and <literal>false</literal>. </para> <para> @@ -3412,23 +3412,23 @@ bar </term> <listitem> <para> - When <literal>on</> (the default), each SQL command is automatically + When <literal>on</literal> (the default), each SQL command is automatically committed upon successful completion. To postpone commit in this - mode, you must enter a <command>BEGIN</> or <command>START - TRANSACTION</> SQL command. When <literal>off</> or unset, SQL + mode, you must enter a <command>BEGIN</command> or <command>START + TRANSACTION</command> SQL command. When <literal>off</literal> or unset, SQL commands are not committed until you explicitly issue - <command>COMMIT</> or <command>END</>. The autocommit-off - mode works by issuing an implicit <command>BEGIN</> for you, just + <command>COMMIT</command> or <command>END</command>. The autocommit-off + mode works by issuing an implicit <command>BEGIN</command> for you, just before any command that is not already in a transaction block and - is not itself a <command>BEGIN</> or other transaction-control + is not itself a <command>BEGIN</command> or other transaction-control command, nor a command that cannot be executed inside a transaction - block (such as <command>VACUUM</>). + block (such as <command>VACUUM</command>). </para> <note> <para> In autocommit-off mode, you must explicitly abandon any failed - transaction by entering <command>ABORT</> or <command>ROLLBACK</>. + transaction by entering <command>ABORT</command> or <command>ROLLBACK</command>. Also keep in mind that if you exit the session without committing, your work will be lost. </para> @@ -3436,7 +3436,7 @@ bar <note> <para> - The autocommit-on mode is <productname>PostgreSQL</>'s traditional + The autocommit-on mode is <productname>PostgreSQL</productname>'s traditional behavior, but autocommit-off is closer to the SQL spec. If you prefer autocommit-off, you might wish to set it in the system-wide <filename>psqlrc</filename> file or your @@ -3496,7 +3496,7 @@ bar <term><varname>ECHO_HIDDEN</varname></term> <listitem> <para> - When this variable is set to <literal>on</> and a backslash command + When this variable is set to <literal>on</literal> and a backslash command queries the database, the query is first shown. This feature helps you to study <productname>PostgreSQL</productname> internals and provide @@ -3504,7 +3504,7 @@ bar on program start-up, use the switch <option>-E</option>.) If you set this variable to the value <literal>noexec</literal>, the queries are just shown but are not actually sent to the server and executed. - The default value is <literal>off</>. + The default value is <literal>off</literal>. </para> </listitem> </varlistentry> @@ -3516,7 +3516,7 @@ bar The current client character set encoding. This is set every time you connect to a database (including program start-up), and when you change the encoding - with <literal>\encoding</>, but it can be changed or unset. + with <literal>\encoding</literal>, but it can be changed or unset. </para> </listitem> </varlistentry> @@ -3525,8 +3525,8 @@ bar <term><varname>ERROR</varname></term> <listitem> <para> - <literal>true</> if the last SQL query failed, <literal>false</> if - it succeeded. See also <varname>SQLSTATE</>. + <literal>true</literal> if the last SQL query failed, <literal>false</literal> if + it succeeded. See also <varname>SQLSTATE</varname>. </para> </listitem> </varlistentry> @@ -3550,7 +3550,7 @@ bar <tip> <para> Although you can use any output format with this feature, - the default <literal>aligned</> format tends to look bad + the default <literal>aligned</literal> format tends to look bad because each group of <varname>FETCH_COUNT</varname> rows will be formatted separately, leading to varying column widths across the row groups. The other output formats work better. @@ -3637,11 +3637,11 @@ bar <term><varname>IGNOREEOF</varname></term> <listitem> <para> - If set to 1 or less, sending an <acronym>EOF</> character (usually - <keycombo action="simul"><keycap>Control</><keycap>D</></>) + If set to 1 or less, sending an <acronym>EOF</acronym> character (usually + <keycombo action="simul"><keycap>Control</keycap><keycap>D</keycap></keycombo>) to an interactive session of <application>psql</application> will terminate the application. If set to a larger numeric value, - that many consecutive <acronym>EOF</> characters must be typed to + that many consecutive <acronym>EOF</acronym> characters must be typed to make an interactive session terminate. If the variable is set to a non-numeric value, it is interpreted as 10. The default is 0. </para> @@ -3673,8 +3673,8 @@ bar <listitem> <para> The primary error message and associated SQLSTATE code for the most - recent failed query in the current <application>psql</> session, or - an empty string and <literal>00000</> if no error has occurred in + recent failed query in the current <application>psql</application> session, or + an empty string and <literal>00000</literal> if no error has occurred in the current session. </para> </listitem> @@ -3690,14 +3690,14 @@ bar </term> <listitem> <para> - When set to <literal>on</>, if a statement in a transaction block + When set to <literal>on</literal>, if a statement in a transaction block generates an error, the error is ignored and the transaction - continues. When set to <literal>interactive</>, such errors are only + continues. When set to <literal>interactive</literal>, such errors are only ignored in interactive sessions, and not when reading script - files. When set to <literal>off</> (the default), a statement in a + files. When set to <literal>off</literal> (the default), a statement in a transaction block that generates an error aborts the entire transaction. The error rollback mode works by issuing an - implicit <command>SAVEPOINT</> for you, just before each command + implicit <command>SAVEPOINT</command> for you, just before each command that is in a transaction block, and then rolling back to the savepoint if the command fails. </para> @@ -3709,7 +3709,7 @@ bar <listitem> <para> By default, command processing continues after an error. When this - variable is set to <literal>on</>, processing will instead stop + variable is set to <literal>on</literal>, processing will instead stop immediately. In interactive mode, <application>psql</application> will return to the command prompt; otherwise, <application>psql</application> will exit, returning @@ -3752,7 +3752,7 @@ bar <term><varname>QUIET</varname></term> <listitem> <para> - Setting this variable to <literal>on</> is equivalent to the command + Setting this variable to <literal>on</literal> is equivalent to the command line option <option>-q</option>. It is probably not too useful in interactive mode. </para> @@ -3775,9 +3775,9 @@ bar <listitem> <para> The server's version number as a string, for - example <literal>9.6.2</>, <literal>10.1</> or <literal>11beta1</>, + example <literal>9.6.2</literal>, <literal>10.1</literal> or <literal>11beta1</literal>, and in numeric form, for - example <literal>90602</> or <literal>100001</>. + example <literal>90602</literal> or <literal>100001</literal>. These are set every time you connect to a database (including program start-up), but can be changed or unset. </para> @@ -3789,13 +3789,13 @@ bar <listitem> <para> This variable can be set to the - values <literal>never</>, <literal>errors</>, or <literal>always</> - to control whether <literal>CONTEXT</> fields are displayed in - messages from the server. The default is <literal>errors</> (meaning + values <literal>never</literal>, <literal>errors</literal>, or <literal>always</literal> + to control whether <literal>CONTEXT</literal> fields are displayed in + messages from the server. The default is <literal>errors</literal> (meaning that context will be shown in error messages, but not in notice or warning messages). This setting has no effect - when <varname>VERBOSITY</> is set to <literal>terse</>. - (See also <command>\errverbose</>, for use when you want a verbose + when <varname>VERBOSITY</varname> is set to <literal>terse</literal>. + (See also <command>\errverbose</command>, for use when you want a verbose version of the error you just got.) </para> </listitem> @@ -3805,7 +3805,7 @@ bar <term><varname>SINGLELINE</varname></term> <listitem> <para> - Setting this variable to <literal>on</> is equivalent to the command + Setting this variable to <literal>on</literal> is equivalent to the command line option <option>-S</option>. </para> </listitem> @@ -3815,7 +3815,7 @@ bar <term><varname>SINGLESTEP</varname></term> <listitem> <para> - Setting this variable to <literal>on</> is equivalent to the command + Setting this variable to <literal>on</literal> is equivalent to the command line option <option>-s</option>. </para> </listitem> @@ -3826,7 +3826,7 @@ bar <listitem> <para> The error code (see <xref linkend="errcodes-appendix">) associated - with the last SQL query's failure, or <literal>00000</> if it + with the last SQL query's failure, or <literal>00000</literal> if it succeeded. </para> </listitem> @@ -3847,10 +3847,10 @@ bar <term><varname>VERBOSITY</varname></term> <listitem> <para> - This variable can be set to the values <literal>default</>, - <literal>verbose</>, or <literal>terse</> to control the verbosity + This variable can be set to the values <literal>default</literal>, + <literal>verbose</literal>, or <literal>terse</literal> to control the verbosity of error reports. - (See also <command>\errverbose</>, for use when you want a verbose + (See also <command>\errverbose</command>, for use when you want a verbose version of the error you just got.) </para> </listitem> @@ -3863,10 +3863,10 @@ bar <listitem> <para> These variables are set at program start-up to reflect - <application>psql</>'s version, respectively as a verbose string, - a short string (e.g., <literal>9.6.2</>, <literal>10.1</>, - or <literal>11beta1</>), and a number (e.g., <literal>90602</> - or <literal>100001</>). They can be changed or unset. + <application>psql</application>'s version, respectively as a verbose string, + a short string (e.g., <literal>9.6.2</literal>, <literal>10.1</literal>, + or <literal>11beta1</literal>), and a number (e.g., <literal>90602</literal> + or <literal>100001</literal>). They can be changed or unset. </para> </listitem> </varlistentry> @@ -3916,7 +3916,7 @@ testdb=> <userinput>SELECT * FROM :"foo";</userinput> <para> Variable interpolation will not be performed within quoted <acronym>SQL</acronym> literals and identifiers. Therefore, a - construction such as <literal>':foo'</> doesn't work to produce a quoted + construction such as <literal>':foo'</literal> doesn't work to produce a quoted literal from a variable's value (and it would be unsafe if it did work, since it wouldn't correctly handle quotes embedded in the value). </para> @@ -3943,7 +3943,7 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:'content');</userinput> </para> <para> - The <literal>:{?<replaceable>name</>}</> special syntax returns TRUE + The <literal>:{?<replaceable>name</replaceable>}</literal> special syntax returns TRUE or FALSE depending on whether the variable exists or not, and is thus always substituted, unless the colon is backslash-escaped. </para> @@ -4086,8 +4086,8 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:'content');</userinput> <listitem> <para> Transaction status: an empty string when not in a transaction - block, or <literal>*</> when in a transaction block, or - <literal>!</> when in a failed transaction block, or <literal>?</> + block, or <literal>*</literal> when in a transaction block, or + <literal>!</literal> when in a failed transaction block, or <literal>?</literal> when the transaction state is indeterminate (for example, because there is no connection). </para> @@ -4098,7 +4098,7 @@ testdb=> <userinput>INSERT INTO my_table VALUES (:'content');</userinput> <term><literal>%l</literal></term> <listitem> <para> - The line number inside the current statement, starting from <literal>1</>. + The line number inside the current statement, starting from <literal>1</literal>. </para> </listitem> </varlistentry> @@ -4186,7 +4186,7 @@ testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# ' supported, although the completion logic makes no claim to be an <acronym>SQL</acronym> parser. The queries generated by tab-completion can also interfere with other SQL commands, e.g. <literal>SET - TRANSACTION ISOLATION LEVEL</>. + TRANSACTION ISOLATION LEVEL</literal>. If for some reason you do not like the tab completion, you can turn it off by putting this in a file named <filename>.inputrc</filename> in your home directory: @@ -4214,8 +4214,8 @@ $endif <listitem> <para> - If <literal>\pset columns</> is zero, controls the - width for the <literal>wrapped</> format and width for determining + If <literal>\pset columns</literal> is zero, controls the + width for the <literal>wrapped</literal> format and width for determining if wide output requires the pager or should be switched to the vertical format in expanded auto mode. </para> @@ -4261,8 +4261,8 @@ $endif <command>\ev</command> is used with a line number argument, this variable specifies the command-line argument used to pass the starting line number to - the user's editor. For editors such as <productname>Emacs</> or - <productname>vi</>, this is a plus sign. Include a trailing + the user's editor. For editors such as <productname>Emacs</productname> or + <productname>vi</productname>, this is a plus sign. Include a trailing space in the value of the variable if there needs to be space between the option name and the line number. Examples: <programlisting> @@ -4304,8 +4304,8 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' pager-related options of the <command>\pset</command> command. These variables are examined in the order listed; the first that is set is used. - If none of them is set, the default is to use <literal>more</> on most - platforms, but <literal>less</> on Cygwin. + If none of them is set, the default is to use <literal>more</literal> on most + platforms, but <literal>less</literal> on Cygwin. </para> </listitem> @@ -4344,8 +4344,8 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -4371,9 +4371,9 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' </para> <para> The system-wide startup file is named <filename>psqlrc</filename> and is - sought in the installation's <quote>system configuration</> directory, + sought in the installation's <quote>system configuration</quote> directory, which is most reliably identified by running <literal>pg_config - --sysconfdir</>. By default this directory will be <filename>../etc/</> + --sysconfdir</literal>. By default this directory will be <filename>../etc/</filename> relative to the directory containing the <productname>PostgreSQL</productname> executables. The name of this directory can be set explicitly via the <envar>PGSYSCONFDIR</envar> @@ -4410,7 +4410,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' </para> <para> The location of the history file can be set explicitly via - the <varname>HISTFILE</varname> <application>psql</> variable or + the <varname>HISTFILE</varname> <application>psql</application> variable or the <envar>PSQL_HISTORY</envar> environment variable. </para> </listitem> @@ -4426,10 +4426,10 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' <listitem> <para><application>psql</application> works best with servers of the same or an older major version. Backslash commands are particularly likely - to fail if the server is of a newer version than <application>psql</> - itself. However, backslash commands of the <literal>\d</> family should + to fail if the server is of a newer version than <application>psql</application> + itself. However, backslash commands of the <literal>\d</literal> family should work with servers of versions back to 7.4, though not necessarily with - servers newer than <application>psql</> itself. The general + servers newer than <application>psql</application> itself. The general functionality of running SQL commands and displaying query results should also work with servers of a newer major version, but this cannot be guaranteed in all cases. @@ -4449,7 +4449,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' <para> Before <productname>PostgreSQL</productname> 9.6, the <option>-c</option> option implied <option>-X</option> - (<option>--no-psqlrc</>); this is no longer the case. + (<option>--no-psqlrc</option>); this is no longer the case. </para> </listitem> @@ -4471,7 +4471,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' <para> <application>psql</application> is built as a <quote>console - application</>. Since the Windows console windows use a different + application</quote>. Since the Windows console windows use a different encoding than the rest of the system, you must take special care when using 8-bit characters within <application>psql</application>. If <application>psql</application> detects a problematic @@ -4490,7 +4490,7 @@ PSQL_EDITOR_LINENUMBER_ARG='--line ' <listitem> <para> - Set the console font to <literal>Lucida Console</>, because the + Set the console font to <literal>Lucida Console</literal>, because the raster font does not work with the ANSI code page. </para> </listitem> diff --git a/doc/src/sgml/ref/reassign_owned.sgml b/doc/src/sgml/ref/reassign_owned.sgml index c1751e7f472..2bbd6b8f07a 100644 --- a/doc/src/sgml/ref/reassign_owned.sgml +++ b/doc/src/sgml/ref/reassign_owned.sgml @@ -88,7 +88,7 @@ REASSIGN OWNED BY { <replaceable class="parameter">old_role</replaceable> | CURR <para> The <command>REASSIGN OWNED</command> command does not affect any - privileges granted to the <replaceable class="parameter">old_roles</> for + privileges granted to the <replaceable class="parameter">old_roles</replaceable> for objects that are not owned by them. Use <command>DROP OWNED</command> to revoke such privileges. </para> diff --git a/doc/src/sgml/ref/refresh_materialized_view.sgml b/doc/src/sgml/ref/refresh_materialized_view.sgml index e56e542eb58..0135d15cece 100644 --- a/doc/src/sgml/ref/refresh_materialized_view.sgml +++ b/doc/src/sgml/ref/refresh_materialized_view.sgml @@ -94,9 +94,9 @@ REFRESH MATERIALIZED VIEW [ CONCURRENTLY ] <replaceable class="parameter">name</ <para> While the default index for future <xref linkend="SQL-CLUSTER"> - operations is retained, <command>REFRESH MATERIALIZED VIEW</> does not + operations is retained, <command>REFRESH MATERIALIZED VIEW</command> does not order the generated rows based on this property. If you want the data - to be ordered upon generation, you must use an <literal>ORDER BY</> + to be ordered upon generation, you must use an <literal>ORDER BY</literal> clause in the backing query. </para> </refsect1> diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml index 09fc61d15b8..3dc2608f76e 100644 --- a/doc/src/sgml/ref/reindex.sgml +++ b/doc/src/sgml/ref/reindex.sgml @@ -46,7 +46,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea <listitem> <para> - An index has become <quote>bloated</>, that is it contains many + An index has become <quote>bloated</quote>, that is it contains many empty or nearly-empty pages. This can occur with B-tree indexes in <productname>PostgreSQL</productname> under certain uncommon access patterns. <command>REINDEX</command> provides a way to reduce @@ -65,12 +65,12 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea <listitem> <para> - An index build with the <literal>CONCURRENTLY</> option failed, leaving - an <quote>invalid</> index. Such indexes are useless but it can be - convenient to use <command>REINDEX</> to rebuild them. Note that - <command>REINDEX</> will not perform a concurrent build. To build the + An index build with the <literal>CONCURRENTLY</literal> option failed, leaving + an <quote>invalid</quote> index. Such indexes are useless but it can be + convenient to use <command>REINDEX</command> to rebuild them. Note that + <command>REINDEX</command> will not perform a concurrent build. To build the index without interfering with production you should drop the index and - reissue the <command>CREATE INDEX CONCURRENTLY</> command. + reissue the <command>CREATE INDEX CONCURRENTLY</command> command. </para> </listitem> @@ -95,7 +95,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea <listitem> <para> Recreate all indexes of the specified table. If the table has a - secondary <quote>TOAST</> table, that is reindexed as well. + secondary <quote>TOAST</quote> table, that is reindexed as well. </para> </listitem> </varlistentry> @@ -105,7 +105,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea <listitem> <para> Recreate all indexes of the specified schema. If a table of this - schema has a secondary <quote>TOAST</> table, that is reindexed as + schema has a secondary <quote>TOAST</quote> table, that is reindexed as well. Indexes on shared system catalogs are also processed. This form of <command>REINDEX</command> cannot be executed inside a transaction block. @@ -144,7 +144,7 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea <para> The name of the specific index, table, or database to be reindexed. Index and table names can be schema-qualified. - Presently, <command>REINDEX DATABASE</> and <command>REINDEX SYSTEM</> + Presently, <command>REINDEX DATABASE</command> and <command>REINDEX SYSTEM</command> can only reindex the current database, so their parameter must match the current database's name. </para> @@ -186,10 +186,10 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea One way to do this is to shut down the server and start a single-user <productname>PostgreSQL</productname> server with the <option>-P</option> option included on its command line. - Then, <command>REINDEX DATABASE</>, <command>REINDEX SYSTEM</>, - <command>REINDEX TABLE</>, or <command>REINDEX INDEX</> can be + Then, <command>REINDEX DATABASE</command>, <command>REINDEX SYSTEM</command>, + <command>REINDEX TABLE</command>, or <command>REINDEX INDEX</command> can be issued, depending on how much you want to reconstruct. If in - doubt, use <command>REINDEX SYSTEM</> to select + doubt, use <command>REINDEX SYSTEM</command> to select reconstruction of all system indexes in the database. Then quit the single-user server session and restart the regular server. See the <xref linkend="app-postgres"> reference page for more @@ -201,8 +201,8 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea Alternatively, a regular server session can be started with <option>-P</option> included in its command line options. The method for doing this varies across clients, but in all - <application>libpq</>-based clients, it is possible to set - the <envar>PGOPTIONS</envar> environment variable to <literal>-P</> + <application>libpq</application>-based clients, it is possible to set + the <envar>PGOPTIONS</envar> environment variable to <literal>-P</literal> 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 @@ -212,12 +212,12 @@ REINDEX [ ( VERBOSE ) ] { INDEX | TABLE | SCHEMA | DATABASE | SYSTEM } <replacea <para> <command>REINDEX</command> 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. <command>REINDEX</> locks out writes + considerations are rather different. <command>REINDEX</command> locks out writes but not reads of the index's parent table. It also takes an exclusive lock on the specific index being processed, which will block reads that attempt - to use that index. In contrast, <command>DROP INDEX</> momentarily takes + to use that index. In contrast, <command>DROP INDEX</command> momentarily takes an exclusive lock on the parent table, blocking both writes and reads. The - subsequent <command>CREATE INDEX</> locks out writes but not reads; since + subsequent <command>CREATE INDEX</command> 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. diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml index e4721d81130..627be6a0add 100644 --- a/doc/src/sgml/ref/reindexdb.sgml +++ b/doc/src/sgml/ref/reindexdb.sgml @@ -109,8 +109,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-a</></term> - <term><option>--all</></term> + <term><option>-a</option></term> + <term><option>--all</option></term> <listitem> <para> Reindex all databases. @@ -119,8 +119,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term> - <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></></term> + <term><option><optional>-d</optional> <replaceable class="parameter">dbname</replaceable></option></term> + <term><option><optional>--dbname=</optional><replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to be reindexed. @@ -134,8 +134,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>reindexdb</application> generates @@ -145,20 +145,20 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-i <replaceable class="parameter">index</replaceable></></term> - <term><option>--index=<replaceable class="parameter">index</replaceable></></term> + <term><option>-i <replaceable class="parameter">index</replaceable></option></term> + <term><option>--index=<replaceable class="parameter">index</replaceable></option></term> <listitem> <para> Recreate <replaceable class="parameter">index</replaceable> only. Multiple indexes can be recreated by writing multiple - <option>-i</> switches. + <option>-i</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-q</></term> - <term><option>--quiet</></term> + <term><option>-q</option></term> + <term><option>--quiet</option></term> <listitem> <para> Do not display progress messages. @@ -167,8 +167,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-s</></term> - <term><option>--system</></term> + <term><option>-s</option></term> + <term><option>--system</option></term> <listitem> <para> Reindex database's system catalogs. @@ -177,32 +177,32 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-S <replaceable class="parameter">schema</replaceable></></term> - <term><option>--schema=<replaceable class="parameter">schema</replaceable></></term> + <term><option>-S <replaceable class="parameter">schema</replaceable></option></term> + <term><option>--schema=<replaceable class="parameter">schema</replaceable></option></term> <listitem> <para> Reindex <replaceable class="parameter">schema</replaceable> only. Multiple schemas can be reindexed by writing multiple - <option>-S</> switches. + <option>-S</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-t <replaceable class="parameter">table</replaceable></></term> - <term><option>--table=<replaceable class="parameter">table</replaceable></></term> + <term><option>-t <replaceable class="parameter">table</replaceable></option></term> + <term><option>--table=<replaceable class="parameter">table</replaceable></option></term> <listitem> <para> Reindex <replaceable class="parameter">table</replaceable> only. Multiple tables can be reindexed by writing multiple - <option>-t</> switches. + <option>-t</option> switches. </para> </listitem> </varlistentry> <varlistentry> - <term><option>-v</></term> - <term><option>--verbose</></term> + <term><option>-v</option></term> + <term><option>--verbose</option></term> <listitem> <para> Print detailed information during processing. @@ -211,8 +211,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>reindexdb</application> version and exit. @@ -221,8 +221,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>reindexdb</application> command line @@ -241,8 +241,8 @@ PostgreSQL documentation <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the server is @@ -253,8 +253,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -265,8 +265,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -275,8 +275,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -290,8 +290,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>reindexdb</application> to prompt for a @@ -304,14 +304,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>reindexdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to discover what other @@ -345,8 +345,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -376,7 +376,7 @@ PostgreSQL documentation <application>reindexdb</application> might need to connect several times to the <productname>PostgreSQL</productname> server, asking for a password each time. It is convenient to have a - <filename>~/.pgpass</> file in such cases. See <xref + <filename>~/.pgpass</filename> file in such cases. See <xref linkend="libpq-pgpass"> for more information. </para> </refsect1> diff --git a/doc/src/sgml/ref/release_savepoint.sgml b/doc/src/sgml/ref/release_savepoint.sgml index b331b7226b0..2e8dcc0746e 100644 --- a/doc/src/sgml/ref/release_savepoint.sgml +++ b/doc/src/sgml/ref/release_savepoint.sgml @@ -109,7 +109,7 @@ COMMIT; <title>Compatibility</title> <para> - This command conforms to the <acronym>SQL</> standard. The standard + This command conforms to the <acronym>SQL</acronym> standard. The standard specifies that the key word <literal>SAVEPOINT</literal> is mandatory, but <productname>PostgreSQL</productname> allows it to be omitted. diff --git a/doc/src/sgml/ref/reset.sgml b/doc/src/sgml/ref/reset.sgml index 98c32078316..b434ad10c28 100644 --- a/doc/src/sgml/ref/reset.sgml +++ b/doc/src/sgml/ref/reset.sgml @@ -42,19 +42,19 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA <para> The default value is defined as the value that the parameter would - have had, if no <command>SET</> had ever been issued for it in the + have had, if no <command>SET</command> 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 <quote>the value that the parameter had at session - start</>, because if the value came from the configuration file, it + start</quote>, because if the value came from the configuration file, it will be reset to whatever is specified by the configuration file now. See <xref linkend="runtime-config"> for details. </para> <para> - The transactional behavior of <command>RESET</> is the same as - <command>SET</>: its effects will be undone by transaction rollback. + The transactional behavior of <command>RESET</command> is the same as + <command>SET</command>: its effects will be undone by transaction rollback. </para> </refsect1> @@ -88,7 +88,7 @@ SET <replaceable class="parameter">configuration_parameter</replaceable> TO DEFA <title>Examples</title> <para> - Set the <varname>timezone</> configuration variable to its default value: + Set the <varname>timezone</varname> configuration variable to its default value: <screen> RESET timezone; </screen></para> diff --git a/doc/src/sgml/ref/revoke.sgml b/doc/src/sgml/ref/revoke.sgml index 91f69af9eed..c893666e83a 100644 --- a/doc/src/sgml/ref/revoke.sgml +++ b/doc/src/sgml/ref/revoke.sgml @@ -130,13 +130,13 @@ REVOKE [ ADMIN OPTION FOR ] 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 - <literal>PUBLIC</literal>. Thus, for example, revoking <literal>SELECT</> privilege + <literal>PUBLIC</literal>. Thus, for example, revoking <literal>SELECT</literal> privilege from <literal>PUBLIC</literal> does not necessarily mean that all roles - have lost <literal>SELECT</> privilege on the object: those who have it granted + have lost <literal>SELECT</literal> privilege on the object: those who have it granted directly or via another role will still have it. Similarly, revoking - <literal>SELECT</> from a user might not prevent that user from using - <literal>SELECT</> if <literal>PUBLIC</literal> or another membership - role still has <literal>SELECT</> rights. + <literal>SELECT</literal> from a user might not prevent that user from using + <literal>SELECT</literal> if <literal>PUBLIC</literal> or another membership + role still has <literal>SELECT</literal> rights. </para> <para> @@ -167,10 +167,10 @@ REVOKE [ ADMIN OPTION FOR ] </para> <para> - When revoking membership in a role, <literal>GRANT OPTION</> is instead - called <literal>ADMIN OPTION</>, but the behavior is similar. + When revoking membership in a role, <literal>GRANT OPTION</literal> is instead + called <literal>ADMIN OPTION</literal>, but the behavior is similar. Note also that this form of the command does not - allow the noise word <literal>GROUP</>. + allow the noise word <literal>GROUP</literal>. </para> </refsect1> @@ -181,7 +181,7 @@ REVOKE [ ADMIN OPTION FOR ] Use <xref linkend="app-psql">'s <command>\dp</command> command to display the privileges granted on existing tables and columns. See <xref linkend="sql-grant"> for information about the - format. For non-table objects there are other <command>\d</> commands + format. For non-table objects there are other <command>\d</command> commands that can display their privileges. </para> @@ -198,12 +198,12 @@ REVOKE [ ADMIN OPTION FOR ] </para> <para> - When a non-owner of an object attempts to <command>REVOKE</> privileges + When a non-owner of an object attempts to <command>REVOKE</command> 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 <command>REVOKE ALL - PRIVILEGES</> forms will issue a warning message if no grant options are + PRIVILEGES</command> 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 @@ -212,7 +212,7 @@ REVOKE [ ADMIN OPTION FOR ] </para> <para> - If a superuser chooses to issue a <command>GRANT</> or <command>REVOKE</> + If a superuser chooses to issue a <command>GRANT</command> or <command>REVOKE</command> 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), @@ -221,26 +221,26 @@ REVOKE [ ADMIN OPTION FOR ] </para> <para> - <command>REVOKE</> can also be done by a role + <command>REVOKE</command> 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 <literal>WITH GRANT OPTION</literal> 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 <literal>WITH GRANT OPTION</literal>. For example, if table - <literal>t1</> is owned by role <literal>g1</>, of which role - <literal>u1</> is a member, then <literal>u1</> can revoke privileges - on <literal>t1</> that are recorded as being granted by <literal>g1</>. - This would include grants made by <literal>u1</> as well as by other - members of role <literal>g1</>. + <literal>t1</literal> is owned by role <literal>g1</literal>, of which role + <literal>u1</literal> is a member, then <literal>u1</literal> can revoke privileges + on <literal>t1</literal> that are recorded as being granted by <literal>g1</literal>. + This would include grants made by <literal>u1</literal> as well as by other + members of role <literal>g1</literal>. </para> <para> - If the role executing <command>REVOKE</> holds privileges + If the role executing <command>REVOKE</command> 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 <command>SET ROLE</> to become the specific - role you want to do the <command>REVOKE</> as. Failure to do so might + it is best practice to use <command>SET ROLE</command> to become the specific + role you want to do the <command>REVOKE</command> as. Failure to do so might lead to revoking privileges other than the ones you intended, or not revoking anything at all. </para> @@ -267,11 +267,11 @@ REVOKE ALL PRIVILEGES ON kinds FROM manuel; </programlisting> Note that this actually means <quote>revoke all privileges that I - granted</>. + granted</quote>. </para> <para> - Revoke membership in role <literal>admins</> from user <literal>joe</>: + Revoke membership in role <literal>admins</literal> from user <literal>joe</literal>: <programlisting> REVOKE admins FROM joe; @@ -285,7 +285,7 @@ REVOKE admins FROM joe; The compatibility notes of the <xref linkend="sql-grant"> command apply analogously to <command>REVOKE</command>. The keyword <literal>RESTRICT</literal> or <literal>CASCADE</literal> - is required according to the standard, but <productname>PostgreSQL</> + is required according to the standard, but <productname>PostgreSQL</productname> assumes <literal>RESTRICT</literal> by default. </para> </refsect1> diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml index b0b1e8d0e3f..1a0e5a0ebcf 100644 --- a/doc/src/sgml/ref/rollback.sgml +++ b/doc/src/sgml/ref/rollback.sgml @@ -59,7 +59,7 @@ ROLLBACK [ WORK | TRANSACTION ] </para> <para> - Issuing <command>ROLLBACK</> outside of a transaction + Issuing <command>ROLLBACK</command> outside of a transaction block emits a warning and otherwise has no effect. </para> </refsect1> diff --git a/doc/src/sgml/ref/rollback_prepared.sgml b/doc/src/sgml/ref/rollback_prepared.sgml index a0ffc650830..6c44049a898 100644 --- a/doc/src/sgml/ref/rollback_prepared.sgml +++ b/doc/src/sgml/ref/rollback_prepared.sgml @@ -75,7 +75,7 @@ ROLLBACK PREPARED <replaceable class="parameter">transaction_id</replaceable> <title id="sql-rollback-prepared-examples-title">Examples</title> <para> Roll back the transaction identified by the transaction - identifier <literal>foobar</>: + identifier <literal>foobar</literal>: <programlisting> ROLLBACK PREPARED 'foobar'; diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml index e8072d8974d..f1da804f67f 100644 --- a/doc/src/sgml/ref/rollback_to.sgml +++ b/doc/src/sgml/ref/rollback_to.sgml @@ -40,7 +40,7 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re </para> <para> - <command>ROLLBACK TO SAVEPOINT</> implicitly destroys all savepoints that + <command>ROLLBACK TO SAVEPOINT</command> implicitly destroys all savepoints that were established after the named savepoint. </para> </refsect1> @@ -50,7 +50,7 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re <variablelist> <varlistentry> - <term><replaceable class="parameter">savepoint_name</></term> + <term><replaceable class="parameter">savepoint_name</replaceable></term> <listitem> <para> The savepoint to roll back to. @@ -77,17 +77,17 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] <replaceable>savepoint_name</re 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 <command>FETCH</> or <command>MOVE</> command inside a + affected by a <command>FETCH</command> or <command>MOVE</command> command inside a savepoint that is later rolled back, the cursor remains at the - position that <command>FETCH</> left it pointing to (that is, the cursor - motion caused by <command>FETCH</> is not rolled back). + position that <command>FETCH</command> left it pointing to (that is, the cursor + motion caused by <command>FETCH</command> is not rolled back). Closing a cursor is not undone by rolling back, either. However, other side-effects caused by the cursor's query (such as - side-effects of volatile functions called by the query) <emphasis>are</> + side-effects of volatile functions called by the query) <emphasis>are</emphasis> 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 - <command>ROLLBACK TO SAVEPOINT</>, the cursor can no longer be used. + <command>ROLLBACK TO SAVEPOINT</command>, the cursor can no longer be used. </para> </refsect1> @@ -133,13 +133,13 @@ COMMIT; <title>Compatibility</title> <para> - The <acronym>SQL</> standard specifies that the key word - <literal>SAVEPOINT</> is mandatory, but <productname>PostgreSQL</> - and <productname>Oracle</> allow it to be omitted. SQL allows - only <literal>WORK</>, not <literal>TRANSACTION</>, as a noise word - after <literal>ROLLBACK</>. Also, SQL has an optional clause - <literal>AND [ NO ] CHAIN</> which is not currently supported by - <productname>PostgreSQL</>. Otherwise, this command conforms to + The <acronym>SQL</acronym> standard specifies that the key word + <literal>SAVEPOINT</literal> is mandatory, but <productname>PostgreSQL</productname> + and <productname>Oracle</productname> allow it to be omitted. SQL allows + only <literal>WORK</literal>, not <literal>TRANSACTION</literal>, as a noise word + after <literal>ROLLBACK</literal>. Also, SQL has an optional clause + <literal>AND [ NO ] CHAIN</literal> which is not currently supported by + <productname>PostgreSQL</productname>. Otherwise, this command conforms to the SQL standard. </para> </refsect1> diff --git a/doc/src/sgml/ref/savepoint.sgml b/doc/src/sgml/ref/savepoint.sgml index 5b944a25615..6d40f4da420 100644 --- a/doc/src/sgml/ref/savepoint.sgml +++ b/doc/src/sgml/ref/savepoint.sgml @@ -114,11 +114,11 @@ COMMIT; <para> SQL requires a savepoint to be destroyed automatically when another savepoint with the same name is established. In - <productname>PostgreSQL</>, the old savepoint is kept, though only the more + <productname>PostgreSQL</productname>, the old savepoint is kept, though only the more recent one will be used when rolling back or releasing. (Releasing the - newer savepoint with <command>RELEASE SAVEPOINT</> will cause the older one - to again become accessible to <command>ROLLBACK TO SAVEPOINT</> and - <command>RELEASE SAVEPOINT</>.) Otherwise, <command>SAVEPOINT</command> is + newer savepoint with <command>RELEASE SAVEPOINT</command> will cause the older one + to again become accessible to <command>ROLLBACK TO SAVEPOINT</command> and + <command>RELEASE SAVEPOINT</command>.) Otherwise, <command>SAVEPOINT</command> is fully SQL conforming. </para> </refsect1> diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml index 971b928a02e..999f9c80cd5 100644 --- a/doc/src/sgml/ref/security_label.sgml +++ b/doc/src/sgml/ref/security_label.sgml @@ -60,12 +60,12 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON 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 - <function>register_label_provider</>. + <function>register_label_provider</function>. </para> <note> <para> - <function>register_label_provider</> is not an SQL function; it can + <function>register_label_provider</function> is not an SQL function; it can only be called from C code loaded into the backend. </para> </note> @@ -74,11 +74,11 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON 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. - <productname>PostgreSQL</> places no restrictions on whether or how a + <productname>PostgreSQL</productname> 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 - <productname>SE-Linux</>. Such systems make all access control decisions + <productname>SE-Linux</productname>. Such systems make all access control decisions based on object labels, rather than traditional discretionary access control (DAC) concepts such as users and groups. </para> @@ -120,14 +120,14 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON <listitem> <para> The mode of a function or aggregate - argument: <literal>IN</>, <literal>OUT</>, - <literal>INOUT</>, or <literal>VARIADIC</>. - If omitted, the default is <literal>IN</>. + argument: <literal>IN</literal>, <literal>OUT</literal>, + <literal>INOUT</literal>, or <literal>VARIADIC</literal>. + If omitted, the default is <literal>IN</literal>. Note that <command>SECURITY LABEL</command> does not actually - pay any attention to <literal>OUT</> arguments, since only the input + pay any attention to <literal>OUT</literal> arguments, since only the input arguments are needed to determine the function's identity. - So it is sufficient to list the <literal>IN</>, <literal>INOUT</>, - and <literal>VARIADIC</> arguments. + So it is sufficient to list the <literal>IN</literal>, <literal>INOUT</literal>, + and <literal>VARIADIC</literal> arguments. </para> </listitem> </varlistentry> @@ -178,7 +178,7 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON <term><replaceable class="parameter">label</replaceable></term> <listitem> <para> - The new security label, written as a string literal; or <literal>NULL</> + The new security label, written as a string literal; or <literal>NULL</literal> to drop the security label. </para> </listitem> diff --git a/doc/src/sgml/ref/select.sgml b/doc/src/sgml/ref/select.sgml index 57f11e66fb6..7355e790f69 100644 --- a/doc/src/sgml/ref/select.sgml +++ b/doc/src/sgml/ref/select.sgml @@ -163,10 +163,10 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] 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 <literal>ALL</literal> is specified. The noise - word <literal>DISTINCT</> can be added to explicitly specify - eliminating duplicate rows. Notice that <literal>DISTINCT</> is + word <literal>DISTINCT</literal> can be added to explicitly specify + eliminating duplicate rows. Notice that <literal>DISTINCT</literal> is the default behavior here, even though <literal>ALL</literal> is - the default for <command>SELECT</> itself. (See + the default for <command>SELECT</command> itself. (See <xref linkend="sql-union" endterm="sql-union-title">, <xref linkend="sql-intersect" endterm="sql-intersect-title">, and <xref linkend="sql-except" endterm="sql-except-title"> below.) @@ -194,7 +194,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <listitem> <para> - If <literal>FOR UPDATE</>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR SHARE</literal> + If <literal>FOR UPDATE</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR SHARE</literal> or <literal>FOR KEY SHARE</literal> is specified, the <command>SELECT</command> statement locks the selected rows @@ -207,7 +207,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <para> You must have <literal>SELECT</literal> privilege on each column used - in a <command>SELECT</> command. The use of <literal>FOR NO KEY UPDATE</>, + in a <command>SELECT</command> command. The use of <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, <literal>FOR SHARE</literal> or <literal>FOR KEY SHARE</literal> requires <literal>UPDATE</literal> privilege as well (for at least one column @@ -226,15 +226,15 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] 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 <command>SELECT</command>, <command>TABLE</>, <command>VALUES</command>, + Each subquery can be a <command>SELECT</command>, <command>TABLE</command>, <command>VALUES</command>, <command>INSERT</command>, <command>UPDATE</command> or <command>DELETE</command> statement. When writing a data-modifying statement (<command>INSERT</command>, <command>UPDATE</command> or <command>DELETE</command>) in - <literal>WITH</>, it is usual to include a <literal>RETURNING</> clause. - It is the output of <literal>RETURNING</>, <emphasis>not</> the underlying + <literal>WITH</literal>, it is usual to include a <literal>RETURNING</literal> clause. + It is the output of <literal>RETURNING</literal>, <emphasis>not</emphasis> the underlying table that the statement modifies, that forms the temporary table that is - read by the primary query. If <literal>RETURNING</> is omitted, the + read by the primary query. If <literal>RETURNING</literal> is omitted, the statement is still executed, but it produces no output so it cannot be referenced as a table by the primary query. </para> @@ -254,7 +254,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <replaceable class="parameter">non_recursive_term</replaceable> UNION [ ALL | DISTINCT ] <replaceable class="parameter">recursive_term</replaceable> </synopsis> where the recursive self-reference must appear on the right-hand - side of the <literal>UNION</>. Only one recursive self-reference + side of the <literal>UNION</literal>. 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 <command>SELECT</command> query in @@ -285,7 +285,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] The primary query and the <literal>WITH</literal> queries are all (notionally) executed at the same time. This implies that the effects of a data-modifying statement in <literal>WITH</literal> cannot be seen from - other parts of the query, other than by reading its <literal>RETURNING</> + other parts of the query, other than by reading its <literal>RETURNING</literal> output. If two such data-modifying statements attempt to modify the same row, the results are unspecified. </para> @@ -303,7 +303,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] tables for the <command>SELECT</command>. If multiple sources are specified, the result is the Cartesian product (cross join) of all the sources. But usually qualification conditions are added (via - <literal>WHERE</>) to restrict the returned rows to a small subset of the + <literal>WHERE</literal>) to restrict the returned rows to a small subset of the Cartesian product. </para> @@ -317,10 +317,10 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <listitem> <para> The name (optionally schema-qualified) of an existing table or view. - If <literal>ONLY</> is specified before the table name, only that - table is scanned. If <literal>ONLY</> is not specified, the table + If <literal>ONLY</literal> is specified before the table name, only that + table is scanned. If <literal>ONLY</literal> is not specified, the table and all its descendant tables (if any) are scanned. Optionally, - <literal>*</> can be specified after the table name to explicitly + <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -330,14 +330,14 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <term><replaceable class="parameter">alias</replaceable></term> <listitem> <para> - A substitute name for the <literal>FROM</> item containing the + A substitute name for the <literal>FROM</literal> 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 - <literal>FROM foo AS f</>, the remainder of the - <command>SELECT</command> must refer to this <literal>FROM</> - item as <literal>f</> not <literal>foo</>. If an alias is + <literal>FROM foo AS f</literal>, the remainder of the + <command>SELECT</command> must refer to this <literal>FROM</literal> + item as <literal>f</literal> not <literal>foo</literal>. 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. </para> @@ -348,12 +348,12 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <term><literal>TABLESAMPLE <replaceable class="parameter">sampling_method</replaceable> ( <replaceable class="parameter">argument</replaceable> [, ...] ) [ REPEATABLE ( <replaceable class="parameter">seed</replaceable> ) ]</literal></term> <listitem> <para> - A <literal>TABLESAMPLE</> clause after - a <replaceable class="parameter">table_name</> indicates that the + A <literal>TABLESAMPLE</literal> clause after + a <replaceable class="parameter">table_name</replaceable> indicates that the specified <replaceable class="parameter">sampling_method</replaceable> should be used to retrieve a subset of the rows in that table. This sampling precedes the application of any other filters such - as <literal>WHERE</> clauses. + as <literal>WHERE</literal> clauses. The standard <productname>PostgreSQL</productname> distribution includes two sampling methods, <literal>BERNOULLI</literal> and <literal>SYSTEM</literal>, and other sampling methods can be @@ -361,11 +361,11 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] </para> <para> - The <literal>BERNOULLI</> and <literal>SYSTEM</> sampling methods - each accept a single <replaceable class="parameter">argument</> + The <literal>BERNOULLI</literal> and <literal>SYSTEM</literal> sampling methods + each accept a single <replaceable class="parameter">argument</replaceable> which is the fraction of the table to sample, expressed as a percentage between 0 and 100. This argument can be - any <type>real</>-valued expression. (Other sampling methods might + any <type>real</type>-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's rows. @@ -383,10 +383,10 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <para> The optional <literal>REPEATABLE</literal> clause specifies - a <replaceable class="parameter">seed</> number or expression to use + a <replaceable class="parameter">seed</replaceable> 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 <replaceable class="parameter">argument</> + specify the same seed and <replaceable class="parameter">argument</replaceable> 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. @@ -420,9 +420,9 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <term><replaceable class="parameter">with_query_name</replaceable></term> <listitem> <para> - A <literal>WITH</> query is referenced by writing its name, + A <literal>WITH</literal> query is referenced by writing its name, just as though the query's name were a table name. (In fact, - the <literal>WITH</> query hides any real table of the same name + the <literal>WITH</literal> 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's name.) @@ -456,8 +456,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <para> Multiple function calls can be combined into a - single <literal>FROM</>-clause item by surrounding them - with <literal>ROWS FROM( ... )</>. The output of such an item is the + single <literal>FROM</literal>-clause item by surrounding them + with <literal>ROWS FROM( ... )</literal>. 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 @@ -467,28 +467,28 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <para> If the function has been defined as returning the - <type>record</> data type, then an alias or the key word - <literal>AS</> must be present, followed by a column + <type>record</type> data type, then an alias or the key word + <literal>AS</literal> must be present, followed by a column definition list in the form <literal>( <replaceable class="parameter">column_name</replaceable> <replaceable class="parameter">data_type</replaceable> <optional>, ... - </>)</literal>. The column definition list must match the + </optional>)</literal>. The column definition list must match the actual number and types of columns returned by the function. </para> <para> - When using the <literal>ROWS FROM( ... )</> syntax, if one of the + When using the <literal>ROWS FROM( ... )</literal> syntax, if one of the functions requires a column definition list, it's preferred to put the column definition list after the function call inside - <literal>ROWS FROM( ... )</>. A column definition list can be placed - after the <literal>ROWS FROM( ... )</> construct only if there's just - a single function and no <literal>WITH ORDINALITY</> clause. + <literal>ROWS FROM( ... )</literal>. A column definition list can be placed + after the <literal>ROWS FROM( ... )</literal> construct only if there's just + a single function and no <literal>WITH ORDINALITY</literal> clause. </para> <para> To use <literal>ORDINALITY</literal> together with a column definition - list, you must use the <literal>ROWS FROM( ... )</> syntax and put the - column definition list inside <literal>ROWS FROM( ... )</>. + list, you must use the <literal>ROWS FROM( ... )</literal> syntax and put the + column definition list inside <literal>ROWS FROM( ... )</literal>. </para> </listitem> </varlistentry> @@ -516,9 +516,9 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] </listitem> </itemizedlist> - For the <literal>INNER</> and <literal>OUTER</> join types, a + For the <literal>INNER</literal> and <literal>OUTER</literal> join types, a join condition must be specified, namely exactly one of - <literal>NATURAL</>, <literal>ON <replaceable + <literal>NATURAL</literal>, <literal>ON <replaceable class="parameter">join_condition</replaceable></literal>, or <literal>USING (<replaceable class="parameter">join_column</replaceable> [, ...])</literal>. @@ -527,46 +527,46 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] </para> <para> - A <literal>JOIN</literal> clause combines two <literal>FROM</> - items, which for convenience we will refer to as <quote>tables</>, - though in reality they can be any type of <literal>FROM</> item. + A <literal>JOIN</literal> clause combines two <literal>FROM</literal> + items, which for convenience we will refer to as <quote>tables</quote>, + though in reality they can be any type of <literal>FROM</literal> item. Use parentheses if necessary to determine the order of nesting. In the absence of parentheses, <literal>JOIN</literal>s nest left-to-right. In any case <literal>JOIN</literal> binds more - tightly than the commas separating <literal>FROM</>-list items. + tightly than the commas separating <literal>FROM</literal>-list items. </para> - <para><literal>CROSS JOIN</> and <literal>INNER JOIN</literal> + <para><literal>CROSS JOIN</literal> and <literal>INNER JOIN</literal> produce a simple Cartesian product, the same result as you get from - listing the two tables at the top level of <literal>FROM</>, + listing the two tables at the top level of <literal>FROM</literal>, but restricted by the join condition (if any). - <literal>CROSS JOIN</> is equivalent to <literal>INNER JOIN ON - (TRUE)</>, that is, no rows are removed by qualification. + <literal>CROSS JOIN</literal> is equivalent to <literal>INNER JOIN ON + (TRUE)</literal>, that is, no rows are removed by qualification. These join types are just a notational convenience, since they - do nothing you couldn't do with plain <literal>FROM</> and - <literal>WHERE</>. + do nothing you couldn't do with plain <literal>FROM</literal> and + <literal>WHERE</literal>. </para> - <para><literal>LEFT OUTER JOIN</> returns all rows in the qualified + <para><literal>LEFT OUTER JOIN</literal> 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 <literal>JOIN</> + right-hand columns. Note that only the <literal>JOIN</literal> clause's own condition is considered while deciding which rows have matches. Outer conditions are applied afterwards. </para> <para> - Conversely, <literal>RIGHT OUTER JOIN</> returns all the + Conversely, <literal>RIGHT OUTER JOIN</literal> 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 <literal>LEFT - OUTER JOIN</> by switching the left and right tables. + OUTER JOIN</literal> by switching the left and right tables. </para> - <para><literal>FULL OUTER JOIN</> returns all the joined rows, plus + <para><literal>FULL OUTER JOIN</literal> 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). @@ -593,7 +593,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] A clause of the form <literal>USING ( a, b, ... )</literal> is shorthand for <literal>ON left_table.a = right_table.a AND left_table.b = right_table.b ...</literal>. Also, - <literal>USING</> implies that only one of each pair of + <literal>USING</literal> implies that only one of each pair of equivalent columns will be included in the join output, not both. </para> @@ -605,10 +605,10 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <listitem> <para> <literal>NATURAL</literal> is shorthand for a - <literal>USING</> list that mentions all columns in the two + <literal>USING</literal> list that mentions all columns in the two tables that have matching names. If there are no common column names, <literal>NATURAL</literal> is equivalent - to <literal>ON TRUE</>. + to <literal>ON TRUE</literal>. </para> </listitem> </varlistentry> @@ -618,32 +618,32 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] <listitem> <para> The <literal>LATERAL</literal> key word can precede a - sub-<command>SELECT</command> <literal>FROM</> item. This allows the - sub-<command>SELECT</command> to refer to columns of <literal>FROM</> - items that appear before it in the <literal>FROM</> list. (Without + sub-<command>SELECT</command> <literal>FROM</literal> item. This allows the + sub-<command>SELECT</command> to refer to columns of <literal>FROM</literal> + items that appear before it in the <literal>FROM</literal> list. (Without <literal>LATERAL</literal>, each sub-<command>SELECT</command> is evaluated independently and so cannot cross-reference any other - <literal>FROM</> item.) + <literal>FROM</literal> item.) </para> <para><literal>LATERAL</literal> can also precede a function-call - <literal>FROM</> item, but in this case it is a noise word, because - the function expression can refer to earlier <literal>FROM</> items + <literal>FROM</literal> item, but in this case it is a noise word, because + the function expression can refer to earlier <literal>FROM</literal> items in any case. </para> <para> A <literal>LATERAL</literal> item can appear at top level in the - <literal>FROM</> list, or within a <literal>JOIN</> tree. In the + <literal>FROM</literal> list, or within a <literal>JOIN</literal> tree. In the latter case it can also refer to any items that are on the left-hand - side of a <literal>JOIN</> that it is on the right-hand side of. + side of a <literal>JOIN</literal> that it is on the right-hand side of. </para> <para> - When a <literal>FROM</> item contains <literal>LATERAL</literal> + When a <literal>FROM</literal> item contains <literal>LATERAL</literal> cross-references, evaluation proceeds as follows: for each row of the - <literal>FROM</> item providing the cross-referenced column(s), or - set of rows of multiple <literal>FROM</> items providing the + <literal>FROM</literal> item providing the cross-referenced column(s), or + set of rows of multiple <literal>FROM</literal> items providing the columns, the <literal>LATERAL</literal> item is evaluated using that row or row set's values of the columns. The resulting row(s) are joined as usual with the rows they were computed from. This is @@ -651,14 +651,14 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] </para> <para> - The column source table(s) must be <literal>INNER</> or - <literal>LEFT</> joined to the <literal>LATERAL</literal> item, else + The column source table(s) must be <literal>INNER</literal> or + <literal>LEFT</literal> joined to the <literal>LATERAL</literal> item, else there would not be a well-defined set of rows from which to compute each set of rows for the <literal>LATERAL</literal> item. Thus, - although a construct such as <literal><replaceable>X</> RIGHT JOIN - LATERAL <replaceable>Y</></literal> is syntactically valid, it is - not actually allowed for <replaceable>Y</> to reference - <replaceable>X</>. + although a construct such as <literal><replaceable>X</replaceable> RIGHT JOIN + LATERAL <replaceable>Y</replaceable></literal> is syntactically valid, it is + not actually allowed for <replaceable>Y</replaceable> to reference + <replaceable>X</replaceable>. </para> </listitem> </varlistentry> @@ -707,13 +707,13 @@ GROUP BY <replaceable class="parameter">grouping_element</replaceable> [, ...] </para> <para> - If any of <literal>GROUPING SETS</>, <literal>ROLLUP</> or - <literal>CUBE</> are present as grouping elements, then the - <literal>GROUP BY</> clause as a whole defines some number of - independent <replaceable>grouping sets</>. The effect of this is - equivalent to constructing a <literal>UNION ALL</> between + If any of <literal>GROUPING SETS</literal>, <literal>ROLLUP</literal> or + <literal>CUBE</literal> are present as grouping elements, then the + <literal>GROUP BY</literal> clause as a whole defines some number of + independent <replaceable>grouping sets</replaceable>. The effect of this is + equivalent to constructing a <literal>UNION ALL</literal> between subqueries with the individual grouping sets as their - <literal>GROUP BY</> clauses. For further details on the handling + <literal>GROUP BY</literal> clauses. For further details on the handling of grouping sets see <xref linkend="queries-grouping-sets">. </para> @@ -744,15 +744,15 @@ GROUP BY <replaceable class="parameter">grouping_element</replaceable> [, ...] <para> Keep in mind that all aggregate functions are evaluated before - evaluating any <quote>scalar</> expressions in the <literal>HAVING</> - clause or <literal>SELECT</> list. This means that, for example, - a <literal>CASE</> expression cannot be used to skip evaluation of + evaluating any <quote>scalar</quote> expressions in the <literal>HAVING</literal> + clause or <literal>SELECT</literal> list. This means that, for example, + a <literal>CASE</literal> expression cannot be used to skip evaluation of an aggregate function; see <xref linkend="syntax-express-eval">. </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, - <literal>FOR SHARE</> and <literal>FOR KEY SHARE</> cannot be + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, + <literal>FOR SHARE</literal> and <literal>FOR KEY SHARE</literal> cannot be specified with <literal>GROUP BY</literal>. </para> </refsect2> @@ -784,9 +784,9 @@ HAVING <replaceable class="parameter">condition</replaceable> <para> The presence of <literal>HAVING</literal> turns a query into a grouped - query even if there is no <literal>GROUP BY</> clause. This is the + query even if there is no <literal>GROUP BY</literal> clause. This is the same as what happens when the query contains aggregate functions but - no <literal>GROUP BY</> clause. All the selected rows are considered to + no <literal>GROUP BY</literal> clause. All the selected rows are considered to form a single group, and the <command>SELECT</command> list and <literal>HAVING</literal> clause can only reference table columns from within aggregate functions. Such a query will emit a single row if the @@ -794,8 +794,8 @@ HAVING <replaceable class="parameter">condition</replaceable> </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, - <literal>FOR SHARE</> and <literal>FOR KEY SHARE</> cannot be + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, + <literal>FOR SHARE</literal> and <literal>FOR KEY SHARE</literal> cannot be specified with <literal>HAVING</literal>. </para> </refsect2> @@ -809,7 +809,7 @@ HAVING <replaceable class="parameter">condition</replaceable> WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceable class="parameter">window_definition</replaceable> ) [, ...] </synopsis> where <replaceable class="parameter">window_name</replaceable> is - a name that can be referenced from <literal>OVER</> clauses or + a name that can be referenced from <literal>OVER</literal> clauses or subsequent window definitions, and <replaceable class="parameter">window_definition</replaceable> is <synopsis> @@ -822,29 +822,29 @@ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceabl <para> If an <replaceable class="parameter">existing_window_name</replaceable> - is specified it must refer to an earlier entry in the <literal>WINDOW</> + is specified it must refer to an earlier entry in the <literal>WINDOW</literal> 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 <literal>PARTITION BY</> clause, and it can specify - <literal>ORDER BY</> only if the copied window does not have one. + specify its own <literal>PARTITION BY</literal> clause, and it can specify + <literal>ORDER BY</literal> 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. </para> <para> - The elements of the <literal>PARTITION BY</> list are interpreted in + The elements of the <literal>PARTITION BY</literal> list are interpreted in much the same fashion as elements of a <xref linkend="sql-groupby" endterm="sql-groupby-title">, 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 <literal>GROUP BY</> + function calls, which are not allowed in a regular <literal>GROUP BY</literal> clause. They are allowed here because windowing occurs after grouping and aggregation. </para> <para> - Similarly, the elements of the <literal>ORDER BY</> list are interpreted + Similarly, the elements of the <literal>ORDER BY</literal> list are interpreted in much the same fashion as elements of an <xref linkend="sql-orderby" endterm="sql-orderby-title">, except that the expressions are always taken as simple expressions and never the name @@ -852,18 +852,18 @@ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceabl </para> <para> - The optional <replaceable class="parameter">frame_clause</> defines - the <firstterm>window frame</> for window functions that depend on the + The optional <replaceable class="parameter">frame_clause</replaceable> defines + the <firstterm>window frame</firstterm> 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 <firstterm>current row</>). - The <replaceable class="parameter">frame_clause</> can be one of + each row of the query (called the <firstterm>current row</firstterm>). + The <replaceable class="parameter">frame_clause</replaceable> can be one of <synopsis> -{ RANGE | ROWS } <replaceable>frame_start</> -{ RANGE | ROWS } BETWEEN <replaceable>frame_start</> AND <replaceable>frame_end</> +{ RANGE | ROWS } <replaceable>frame_start</replaceable> +{ RANGE | ROWS } BETWEEN <replaceable>frame_start</replaceable> AND <replaceable>frame_end</replaceable> </synopsis> - where <replaceable>frame_start</> and <replaceable>frame_end</> can be + where <replaceable>frame_start</replaceable> and <replaceable>frame_end</replaceable> can be one of <synopsis> @@ -874,34 +874,34 @@ CURRENT ROW UNBOUNDED FOLLOWING </synopsis> - If <replaceable>frame_end</> is omitted it defaults to <literal>CURRENT - ROW</>. Restrictions are that - <replaceable>frame_start</> cannot be <literal>UNBOUNDED FOLLOWING</>, - <replaceable>frame_end</> cannot be <literal>UNBOUNDED PRECEDING</>, - and the <replaceable>frame_end</> choice cannot appear earlier in the - above list than the <replaceable>frame_start</> choice — for example - <literal>RANGE BETWEEN CURRENT ROW AND <replaceable>value</> + If <replaceable>frame_end</replaceable> is omitted it defaults to <literal>CURRENT + ROW</literal>. Restrictions are that + <replaceable>frame_start</replaceable> cannot be <literal>UNBOUNDED FOLLOWING</literal>, + <replaceable>frame_end</replaceable> cannot be <literal>UNBOUNDED PRECEDING</literal>, + and the <replaceable>frame_end</replaceable> choice cannot appear earlier in the + above list than the <replaceable>frame_start</replaceable> choice — for example + <literal>RANGE BETWEEN CURRENT ROW AND <replaceable>value</replaceable> PRECEDING</literal> is not allowed. </para> <para> - The default framing option is <literal>RANGE UNBOUNDED PRECEDING</>, + The default framing option is <literal>RANGE UNBOUNDED PRECEDING</literal>, which is the same as <literal>RANGE BETWEEN UNBOUNDED PRECEDING AND - CURRENT ROW</>; it sets the frame to be all rows from the partition start + CURRENT ROW</literal>; it sets the frame to be all rows from the partition start up through the current row's last peer (a row that <literal>ORDER - BY</> considers equivalent to the current row, or all rows if there - is no <literal>ORDER BY</>). - In general, <literal>UNBOUNDED PRECEDING</> means that the frame + BY</literal> considers equivalent to the current row, or all rows if there + is no <literal>ORDER BY</literal>). + In general, <literal>UNBOUNDED PRECEDING</literal> means that the frame starts with the first row of the partition, and similarly - <literal>UNBOUNDED FOLLOWING</> means that the frame ends with the last - row of the partition (regardless of <literal>RANGE</> or <literal>ROWS</> - mode). In <literal>ROWS</> mode, <literal>CURRENT ROW</> + <literal>UNBOUNDED FOLLOWING</literal> means that the frame ends with the last + row of the partition (regardless of <literal>RANGE</literal> or <literal>ROWS</literal> + mode). In <literal>ROWS</literal> mode, <literal>CURRENT ROW</literal> means that the frame starts or ends with the current row; but in - <literal>RANGE</> mode it means that the frame starts or ends with - the current row's first or last peer in the <literal>ORDER BY</> ordering. - The <replaceable>value</> <literal>PRECEDING</> and - <replaceable>value</> <literal>FOLLOWING</> cases are currently only - allowed in <literal>ROWS</> mode. They indicate that the frame starts + <literal>RANGE</literal> mode it means that the frame starts or ends with + the current row's first or last peer in the <literal>ORDER BY</literal> ordering. + The <replaceable>value</replaceable> <literal>PRECEDING</literal> and + <replaceable>value</replaceable> <literal>FOLLOWING</literal> cases are currently only + allowed in <literal>ROWS</literal> mode. They indicate that the frame starts or ends with the row that many rows before or after the current row. <replaceable>value</replaceable> must be an integer expression not containing any variables, aggregate functions, or window functions. @@ -910,32 +910,32 @@ UNBOUNDED FOLLOWING </para> <para> - Beware that the <literal>ROWS</> options can produce unpredictable - results if the <literal>ORDER BY</> ordering does not order the rows - uniquely. The <literal>RANGE</> options are designed to ensure that - rows that are peers in the <literal>ORDER BY</> ordering are treated + Beware that the <literal>ROWS</literal> options can produce unpredictable + results if the <literal>ORDER BY</literal> ordering does not order the rows + uniquely. The <literal>RANGE</literal> options are designed to ensure that + rows that are peers in the <literal>ORDER BY</literal> ordering are treated alike; all peer rows will be in the same frame. </para> <para> The purpose of a <literal>WINDOW</literal> clause is to specify the - behavior of <firstterm>window functions</> appearing in the query's + behavior of <firstterm>window functions</firstterm> appearing in the query's <xref linkend="sql-select-list" endterm="sql-select-list-title"> or <xref linkend="sql-orderby" endterm="sql-orderby-title">. These functions can reference the <literal>WINDOW</literal> clause entries by name - in their <literal>OVER</> clauses. A <literal>WINDOW</literal> clause + in their <literal>OVER</literal> clauses. A <literal>WINDOW</literal> 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 <literal>WINDOW</literal> clause at all, since a window function call can specify its window definition directly in - its <literal>OVER</> clause. However, the <literal>WINDOW</literal> + its <literal>OVER</literal> clause. However, the <literal>WINDOW</literal> clause saves typing when the same window definition is needed for more than one window function. </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, - <literal>FOR SHARE</> and <literal>FOR KEY SHARE</> cannot be + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, + <literal>FOR SHARE</literal> and <literal>FOR KEY SHARE</literal> cannot be specified with <literal>WINDOW</literal>. </para> @@ -952,20 +952,20 @@ UNBOUNDED FOLLOWING <para> The <command>SELECT</command> list (between the key words - <literal>SELECT</> and <literal>FROM</>) specifies expressions + <literal>SELECT</literal> and <literal>FROM</literal>) specifies expressions that form the output rows of the <command>SELECT</command> statement. The expressions can (and usually do) refer to columns - computed in the <literal>FROM</> clause. + computed in the <literal>FROM</literal> clause. </para> <para> Just as in a table, every output column of a <command>SELECT</command> has a name. In a simple <command>SELECT</command> this name is just - used to label the column for display, but when the <command>SELECT</> + used to label the column for display, but when the <command>SELECT</command> 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 - <literal>AS</> <replaceable class="parameter">output_name</replaceable> + <literal>AS</literal> <replaceable class="parameter">output_name</replaceable> after the column's expression. (You can omit <literal>AS</literal>, but only if the desired output name does not match any <productname>PostgreSQL</productname> keyword (see <xref @@ -982,8 +982,8 @@ UNBOUNDED FOLLOWING <para> An output column's name can be used to refer to the column's value in - <literal>ORDER BY</> and <literal>GROUP BY</> clauses, but not in the - <literal>WHERE</> or <literal>HAVING</> clauses; there you must write + <literal>ORDER BY</literal> and <literal>GROUP BY</literal> clauses, but not in the + <literal>WHERE</literal> or <literal>HAVING</literal> clauses; there you must write out the expression instead. </para> @@ -993,7 +993,7 @@ UNBOUNDED FOLLOWING rows. Also, you can write <literal><replaceable class="parameter">table_name</replaceable>.*</literal> as a shorthand for the columns coming from just that table. In these - cases it is not possible to specify new names with <literal>AS</>; + cases it is not possible to specify new names with <literal>AS</literal>; the output column names will be the same as the table columns' names. </para> @@ -1008,11 +1008,11 @@ UNBOUNDED FOLLOWING 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. - <productname>PostgreSQL</> will effectively evaluate output expressions + <productname>PostgreSQL</productname> will effectively evaluate output expressions after sorting and limiting, so long as those expressions are not referenced in <literal>DISTINCT</literal>, <literal>ORDER BY</literal> or <literal>GROUP BY</literal>. (As a counterexample, <literal>SELECT - f(x) FROM tab ORDER BY 1</> clearly must evaluate <function>f(x)</> + f(x) FROM tab ORDER BY 1</literal> clearly must evaluate <function>f(x)</function> before sorting.) Output expressions that contain set-returning functions are effectively evaluated after sorting and before limiting, so that <literal>LIMIT</literal> will act to cut off the output from a @@ -1021,7 +1021,7 @@ UNBOUNDED FOLLOWING <note> <para> - <productname>PostgreSQL</> versions before 9.6 did not provide any + <productname>PostgreSQL</productname> 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. </para> @@ -1032,9 +1032,9 @@ UNBOUNDED FOLLOWING <title id="sql-distinct-title"><literal>DISTINCT</literal> Clause</title> <para> - If <literal>SELECT DISTINCT</> is specified, all duplicate rows are + If <literal>SELECT DISTINCT</literal> is specified, all duplicate rows are removed from the result set (one row is kept from each group of - duplicates). <literal>SELECT ALL</> specifies the opposite: all rows are + duplicates). <literal>SELECT ALL</literal> specifies the opposite: all rows are kept; that is the default. </para> @@ -1044,9 +1044,9 @@ UNBOUNDED FOLLOWING keeps only the first row of each set of rows where the given expressions evaluate to equal. The <literal>DISTINCT ON</literal> expressions are interpreted using the same rules as for - <literal>ORDER BY</> (see above). Note that the <quote>first + <literal>ORDER BY</literal> (see above). Note that the <quote>first row</quote> of each set is unpredictable unless <literal>ORDER - BY</> is used to ensure that the desired row appears first. For + BY</literal> is used to ensure that the desired row appears first. For example: <programlisting> SELECT DISTINCT ON (location) location, time, report @@ -1054,21 +1054,21 @@ SELECT DISTINCT ON (location) location, time, report ORDER BY location, time DESC; </programlisting> retrieves the most recent weather report for each location. But - if we had not used <literal>ORDER BY</> to force descending order + if we had not used <literal>ORDER BY</literal> to force descending order of time values for each location, we'd have gotten a report from an unpredictable time for each location. </para> <para> - The <literal>DISTINCT ON</> expression(s) must match the leftmost - <literal>ORDER BY</> expression(s). The <literal>ORDER BY</> clause + The <literal>DISTINCT ON</literal> expression(s) must match the leftmost + <literal>ORDER BY</literal> expression(s). The <literal>ORDER BY</literal> clause will normally contain additional expression(s) that determine the - desired precedence of rows within each <literal>DISTINCT ON</> group. + desired precedence of rows within each <literal>DISTINCT ON</literal> group. </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, - <literal>FOR SHARE</> and <literal>FOR KEY SHARE</> cannot be + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, + <literal>FOR SHARE</literal> and <literal>FOR KEY SHARE</literal> cannot be specified with <literal>DISTINCT</literal>. </para> </refsect2> @@ -1082,9 +1082,9 @@ SELECT DISTINCT ON (location) location, time, report <replaceable class="parameter">select_statement</replaceable> UNION [ ALL | DISTINCT ] <replaceable class="parameter">select_statement</replaceable> </synopsis><replaceable class="parameter">select_statement</replaceable> is any <command>SELECT</command> statement without an <literal>ORDER - BY</>, <literal>LIMIT</>, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</literal>, + BY</literal>, <literal>LIMIT</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, <literal>FOR SHARE</literal>, or <literal>FOR KEY SHARE</literal> clause. - (<literal>ORDER BY</> and <literal>LIMIT</> can be attached to a + (<literal>ORDER BY</literal> and <literal>LIMIT</literal> 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 <literal>UNION</literal>, not to its right-hand input @@ -1103,26 +1103,26 @@ SELECT DISTINCT ON (location) location, time, report </para> <para> - The result of <literal>UNION</> does not contain any duplicate - rows unless the <literal>ALL</> option is specified. - <literal>ALL</> prevents elimination of duplicates. (Therefore, - <literal>UNION ALL</> is usually significantly quicker than - <literal>UNION</>; use <literal>ALL</> when you can.) - <literal>DISTINCT</> can be written to explicitly specify the + The result of <literal>UNION</literal> does not contain any duplicate + rows unless the <literal>ALL</literal> option is specified. + <literal>ALL</literal> prevents elimination of duplicates. (Therefore, + <literal>UNION ALL</literal> is usually significantly quicker than + <literal>UNION</literal>; use <literal>ALL</literal> when you can.) + <literal>DISTINCT</literal> can be written to explicitly specify the default behavior of eliminating duplicate rows. </para> <para> - Multiple <literal>UNION</> operators in the same + Multiple <literal>UNION</literal> operators in the same <command>SELECT</command> statement are evaluated left to right, unless otherwise indicated by parentheses. </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, <literal>FOR SHARE</> and - <literal>FOR KEY SHARE</> cannot be - specified either for a <literal>UNION</> result or for any input of a - <literal>UNION</>. + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, <literal>FOR SHARE</literal> and + <literal>FOR KEY SHARE</literal> cannot be + specified either for a <literal>UNION</literal> result or for any input of a + <literal>UNION</literal>. </para> </refsect2> @@ -1135,8 +1135,8 @@ SELECT DISTINCT ON (location) location, time, report <replaceable class="parameter">select_statement</replaceable> INTERSECT [ ALL | DISTINCT ] <replaceable class="parameter">select_statement</replaceable> </synopsis><replaceable class="parameter">select_statement</replaceable> is any <command>SELECT</command> statement without an <literal>ORDER - BY</>, <literal>LIMIT</>, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</literal>, - <literal>FOR SHARE</literal>, or <literal>FOR KEY SHARE</> clause. + BY</literal>, <literal>LIMIT</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, + <literal>FOR SHARE</literal>, or <literal>FOR KEY SHARE</literal> clause. </para> <para> @@ -1148,11 +1148,11 @@ SELECT DISTINCT ON (location) location, time, report <para> The result of <literal>INTERSECT</literal> does not contain any - duplicate rows unless the <literal>ALL</> option is specified. - With <literal>ALL</>, a row that has <replaceable>m</> duplicates in the - left table and <replaceable>n</> duplicates in the right table will appear - min(<replaceable>m</>,<replaceable>n</>) times in the result set. - <literal>DISTINCT</> can be written to explicitly specify the + duplicate rows unless the <literal>ALL</literal> option is specified. + With <literal>ALL</literal>, a row that has <replaceable>m</replaceable> duplicates in the + left table and <replaceable>n</replaceable> duplicates in the right table will appear + min(<replaceable>m</replaceable>,<replaceable>n</replaceable>) times in the result set. + <literal>DISTINCT</literal> can be written to explicitly specify the default behavior of eliminating duplicate rows. </para> @@ -1167,10 +1167,10 @@ SELECT DISTINCT ON (location) location, time, report </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, <literal>FOR SHARE</> and - <literal>FOR KEY SHARE</> cannot be - specified either for an <literal>INTERSECT</> result or for any input of - an <literal>INTERSECT</>. + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, <literal>FOR SHARE</literal> and + <literal>FOR KEY SHARE</literal> cannot be + specified either for an <literal>INTERSECT</literal> result or for any input of + an <literal>INTERSECT</literal>. </para> </refsect2> @@ -1183,8 +1183,8 @@ SELECT DISTINCT ON (location) location, time, report <replaceable class="parameter">select_statement</replaceable> EXCEPT [ ALL | DISTINCT ] <replaceable class="parameter">select_statement</replaceable> </synopsis><replaceable class="parameter">select_statement</replaceable> is any <command>SELECT</command> statement without an <literal>ORDER - BY</>, <literal>LIMIT</>, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</literal>, - <literal>FOR SHARE</literal>, or <literal>FOR KEY SHARE</> clause. + BY</literal>, <literal>LIMIT</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, + <literal>FOR SHARE</literal>, or <literal>FOR KEY SHARE</literal> clause. </para> <para> @@ -1195,26 +1195,26 @@ SELECT DISTINCT ON (location) location, time, report <para> The result of <literal>EXCEPT</literal> does not contain any - duplicate rows unless the <literal>ALL</> option is specified. - With <literal>ALL</>, a row that has <replaceable>m</> duplicates in the - left table and <replaceable>n</> duplicates in the right table will appear - max(<replaceable>m</>-<replaceable>n</>,0) times in the result set. - <literal>DISTINCT</> can be written to explicitly specify the + duplicate rows unless the <literal>ALL</literal> option is specified. + With <literal>ALL</literal>, a row that has <replaceable>m</replaceable> duplicates in the + left table and <replaceable>n</replaceable> duplicates in the right table will appear + max(<replaceable>m</replaceable>-<replaceable>n</replaceable>,0) times in the result set. + <literal>DISTINCT</literal> can be written to explicitly specify the default behavior of eliminating duplicate rows. </para> <para> Multiple <literal>EXCEPT</literal> operators in the same <command>SELECT</command> statement are evaluated left to right, - unless parentheses dictate otherwise. <literal>EXCEPT</> binds at - the same level as <literal>UNION</>. + unless parentheses dictate otherwise. <literal>EXCEPT</literal> binds at + the same level as <literal>UNION</literal>. </para> <para> - Currently, <literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, <literal>FOR SHARE</> and - <literal>FOR KEY SHARE</> cannot be - specified either for an <literal>EXCEPT</> result or for any input of - an <literal>EXCEPT</>. + Currently, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, <literal>FOR SHARE</literal> and + <literal>FOR KEY SHARE</literal> cannot be + specified either for an <literal>EXCEPT</literal> result or for any input of + an <literal>EXCEPT</literal>. </para> </refsect2> @@ -1247,7 +1247,7 @@ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | 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 - <literal>AS</> clause. + <literal>AS</literal> clause. </para> <para> @@ -1258,59 +1258,59 @@ ORDER BY <replaceable class="parameter">expression</replaceable> [ ASC | DESC | <programlisting> SELECT name FROM distributors ORDER BY code; </programlisting> - A limitation of this feature is that an <literal>ORDER BY</> - clause applying to the result of a <literal>UNION</>, - <literal>INTERSECT</>, or <literal>EXCEPT</> clause can only + A limitation of this feature is that an <literal>ORDER BY</literal> + clause applying to the result of a <literal>UNION</literal>, + <literal>INTERSECT</literal>, or <literal>EXCEPT</literal> clause can only specify an output column name or number, not an expression. </para> <para> - If an <literal>ORDER BY</> expression is a simple name that + If an <literal>ORDER BY</literal> expression is a simple name that matches both an output column name and an input column name, - <literal>ORDER BY</> will interpret it as the output column name. - This is the opposite of the choice that <literal>GROUP BY</> will + <literal>ORDER BY</literal> will interpret it as the output column name. + This is the opposite of the choice that <literal>GROUP BY</literal> will make in the same situation. This inconsistency is made to be compatible with the SQL standard. </para> <para> - Optionally one can add the key word <literal>ASC</> (ascending) or - <literal>DESC</> (descending) after any expression in the - <literal>ORDER BY</> clause. If not specified, <literal>ASC</> is + Optionally one can add the key word <literal>ASC</literal> (ascending) or + <literal>DESC</literal> (descending) after any expression in the + <literal>ORDER BY</literal> clause. If not specified, <literal>ASC</literal> is assumed by default. Alternatively, a specific ordering operator - name can be specified in the <literal>USING</> clause. + name can be specified in the <literal>USING</literal> clause. An ordering operator must be a less-than or greater-than member of some B-tree operator family. - <literal>ASC</> is usually equivalent to <literal>USING <</> and - <literal>DESC</> is usually equivalent to <literal>USING ></>. + <literal>ASC</literal> is usually equivalent to <literal>USING <</literal> and + <literal>DESC</literal> is usually equivalent to <literal>USING ></literal>. (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.) </para> <para> - If <literal>NULLS LAST</> is specified, null values sort after all - non-null values; if <literal>NULLS FIRST</> is specified, null values + If <literal>NULLS LAST</literal> is specified, null values sort after all + non-null values; if <literal>NULLS FIRST</literal> is specified, null values sort before all non-null values. If neither is specified, the default - behavior is <literal>NULLS LAST</> when <literal>ASC</> is specified - or implied, and <literal>NULLS FIRST</> when <literal>DESC</> is specified + behavior is <literal>NULLS LAST</literal> when <literal>ASC</literal> is specified + or implied, and <literal>NULLS FIRST</literal> when <literal>DESC</literal> is specified (thus, the default is to act as though nulls are larger than non-nulls). - When <literal>USING</> is specified, the default nulls ordering depends + When <literal>USING</literal> is specified, the default nulls ordering depends on whether the operator is a less-than or greater-than operator. </para> <para> Note that ordering options apply only to the expression they follow; - for example <literal>ORDER BY x, y DESC</> does not mean - the same thing as <literal>ORDER BY x DESC, y DESC</>. + for example <literal>ORDER BY x, y DESC</literal> does not mean + the same thing as <literal>ORDER BY x DESC, y DESC</literal>. </para> <para> 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 <literal>COLLATE</> clause in the + a <literal>COLLATE</literal> clause in the <replaceable class="parameter">expression</replaceable>, for example - <literal>ORDER BY mycolumn COLLATE "en_US"</>. + <literal>ORDER BY mycolumn COLLATE "en_US"</literal>. For more information see <xref linkend="sql-syntax-collate-exprs"> and <xref linkend="collation">. </para> @@ -1337,60 +1337,60 @@ OFFSET <replaceable class="parameter">start</replaceable> <para> If the <replaceable class="parameter">count</replaceable> expression - evaluates to NULL, it is treated as <literal>LIMIT ALL</>, i.e., no + evaluates to NULL, it is treated as <literal>LIMIT ALL</literal>, i.e., no limit. If <replaceable class="parameter">start</replaceable> evaluates - to NULL, it is treated the same as <literal>OFFSET 0</>. + to NULL, it is treated the same as <literal>OFFSET 0</literal>. </para> <para> SQL:2008 introduced a different syntax to achieve the same result, - which <productname>PostgreSQL</> also supports. It is: + which <productname>PostgreSQL</productname> also supports. It is: <synopsis> OFFSET <replaceable class="parameter">start</replaceable> { ROW | ROWS } FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] { ROW | ROWS } ONLY </synopsis> In this syntax, to write anything except a simple integer constant for - <replaceable class="parameter">start</> or <replaceable + <replaceable class="parameter">start</replaceable> or <replaceable class="parameter">count</replaceable>, you must write parentheses around it. - If <replaceable class="parameter">count</> is - omitted in a <literal>FETCH</> clause, it defaults to 1. + If <replaceable class="parameter">count</replaceable> is + omitted in a <literal>FETCH</literal> clause, it defaults to 1. <literal>ROW</literal> and <literal>ROWS</literal> as well as <literal>FIRST</literal> and <literal>NEXT</literal> are noise words that don't influence the effects of these clauses. According to the standard, the <literal>OFFSET</literal> clause must come before the <literal>FETCH</literal> clause if both are present; but - <productname>PostgreSQL</> is laxer and allows either order. + <productname>PostgreSQL</productname> is laxer and allows either order. </para> <para> - When using <literal>LIMIT</>, it is a good idea to use an - <literal>ORDER BY</> clause that constrains the result rows into a + When using <literal>LIMIT</literal>, it is a good idea to use an + <literal>ORDER BY</literal> clause that constrains the result rows into a unique order. Otherwise you will get an unpredictable subset of the query's rows — you might be asking for the tenth through twentieth rows, but tenth through twentieth in what ordering? You - don't know what ordering unless you specify <literal>ORDER BY</>. + don't know what ordering unless you specify <literal>ORDER BY</literal>. </para> <para> - The query planner takes <literal>LIMIT</> into account when + The query planner takes <literal>LIMIT</literal> 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 <literal>LIMIT</> and <literal>OFFSET</>. Thus, using - different <literal>LIMIT</>/<literal>OFFSET</> values to select + for <literal>LIMIT</literal> and <literal>OFFSET</literal>. Thus, using + different <literal>LIMIT</literal>/<literal>OFFSET</literal> values to select different subsets of a query result <emphasis>will give inconsistent results</emphasis> unless you enforce a predictable - result ordering with <literal>ORDER BY</>. This is not a bug; it + result ordering with <literal>ORDER BY</literal>. 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 - <literal>ORDER BY</> is used to constrain the order. + <literal>ORDER BY</literal> is used to constrain the order. </para> <para> - It is even possible for repeated executions of the same <literal>LIMIT</> + It is even possible for repeated executions of the same <literal>LIMIT</literal> query to return different subsets of the rows of a table, if there - is not an <literal>ORDER BY</> to enforce selection of a deterministic + is not an <literal>ORDER BY</literal> 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. </para> @@ -1400,9 +1400,9 @@ FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] { <title id="sql-for-update-share-title">The Locking Clause</title> <para> - <literal>FOR UPDATE</>, <literal>FOR NO KEY UPDATE</>, <literal>FOR SHARE</> - and <literal>FOR KEY SHARE</> - are <firstterm>locking clauses</>; they affect how <literal>SELECT</> + <literal>FOR UPDATE</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR SHARE</literal> + and <literal>FOR KEY SHARE</literal> + are <firstterm>locking clauses</firstterm>; they affect how <literal>SELECT</literal> locks rows as they are obtained from the table. </para> @@ -1410,10 +1410,10 @@ FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] { The locking clause has the general form <synopsis> -FOR <replaceable>lock_strength</> [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT | SKIP LOCKED ] +FOR <replaceable>lock_strength</replaceable> [ OF <replaceable class="parameter">table_name</replaceable> [, ...] ] [ NOWAIT | SKIP LOCKED ] </synopsis> - where <replaceable>lock_strength</> can be one of + where <replaceable>lock_strength</replaceable> can be one of <synopsis> UPDATE @@ -1430,20 +1430,20 @@ KEY SHARE <para> To prevent the operation from waiting for other transactions to commit, - use either the <literal>NOWAIT</> or <literal>SKIP LOCKED</literal> - option. With <literal>NOWAIT</>, the statement reports an error, rather + use either the <literal>NOWAIT</literal> or <literal>SKIP LOCKED</literal> + option. With <literal>NOWAIT</literal>, the statement reports an error, rather than waiting, if a selected row cannot be locked immediately. With <literal>SKIP LOCKED</literal>, 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 <literal>NOWAIT</> and <literal>SKIP LOCKED</literal> apply only + Note that <literal>NOWAIT</literal> and <literal>SKIP LOCKED</literal> apply only to the row-level lock(s) — the required <literal>ROW SHARE</literal> table-level lock is still taken in the ordinary way (see <xref linkend="mvcc">). You can use <xref linkend="sql-lock"> - with the <literal>NOWAIT</> option first, + with the <literal>NOWAIT</literal> option first, if you need to acquire the table-level lock without waiting. </para> @@ -1457,9 +1457,9 @@ KEY SHARE 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 <literal>WITH</> queries referenced by the primary query. - If you want row locking to occur within a <literal>WITH</> query, specify - a locking clause within the <literal>WITH</> query. + do not apply to <literal>WITH</literal> queries referenced by the primary query. + If you want row locking to occur within a <literal>WITH</literal> query, specify + a locking clause within the <literal>WITH</literal> query. </para> <para> @@ -1469,7 +1469,7 @@ KEY SHARE 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 <literal>NOWAIT</> if that is specified in any of the clauses + as <literal>NOWAIT</literal> if that is specified in any of the clauses affecting it. Otherwise, it is processed as <literal>SKIP LOCKED</literal> if that is specified in any of the clauses affecting it. @@ -1483,16 +1483,16 @@ KEY SHARE <para> When a locking clause - appears at the top level of a <command>SELECT</> query, the rows that + appears at the top level of a <command>SELECT</command> 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 - <literal>LIMIT</> is used, locking stops + <literal>LIMIT</literal> is used, locking stops once enough rows have been returned to satisfy the limit (but note that - rows skipped over by <literal>OFFSET</> will get locked). Similarly, + rows skipped over by <literal>OFFSET</literal> will get locked). Similarly, if a locking clause is used in a cursor's query, only rows actually fetched or stepped past by the cursor will be locked. @@ -1500,7 +1500,7 @@ KEY SHARE <para> When a locking clause - appears in a sub-<command>SELECT</>, the rows locked are those + appears in a sub-<command>SELECT</command>, 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 @@ -1508,7 +1508,7 @@ KEY SHARE <programlisting> SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss WHERE col1 = 5; </programlisting> - will lock only rows having <literal>col1 = 5</>, even though that + will lock only rows having <literal>col1 = 5</literal>, even though that condition is not textually within the sub-query. </para> @@ -1522,18 +1522,18 @@ SAVEPOINT s; UPDATE mytable SET ... WHERE key = 1; ROLLBACK TO s; </programlisting> - would fail to preserve the <literal>FOR UPDATE</> lock after the - <command>ROLLBACK TO</>. This has been fixed in release 9.3. + would fail to preserve the <literal>FOR UPDATE</literal> lock after the + <command>ROLLBACK TO</command>. This has been fixed in release 9.3. </para> <caution> <para> - It is possible for a <command>SELECT</> command running at the <literal>READ + It is possible for a <command>SELECT</command> command running at the <literal>READ COMMITTED</literal> transaction isolation level and using <literal>ORDER BY</literal> and a locking clause to return rows out of - order. This is because <literal>ORDER BY</> is applied first. + order. This is because <literal>ORDER BY</literal> 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 <literal>SELECT</> unblocks, some + on one or more of the rows. Once the <literal>SELECT</literal> 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 @@ -1542,11 +1542,11 @@ ROLLBACK TO s; <programlisting> SELECT * FROM (SELECT * FROM mytable FOR UPDATE) ss ORDER BY column1; </programlisting> - Note that this will result in locking all rows of <structname>mytable</>, - whereas <literal>FOR UPDATE</> at the top level would lock only the + Note that this will result in locking all rows of <structname>mytable</structname>, + whereas <literal>FOR UPDATE</literal> at the top level would lock only the actually returned rows. This can make for a significant performance - difference, particularly if the <literal>ORDER BY</> is combined with - <literal>LIMIT</> or other restrictions. So this technique is recommended + difference, particularly if the <literal>ORDER BY</literal> is combined with + <literal>LIMIT</literal> 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. </para> @@ -1573,11 +1573,11 @@ TABLE <replaceable class="parameter">name</replaceable> SELECT * FROM <replaceable class="parameter">name</replaceable> </programlisting> It can be used as a top-level command or as a space-saving syntax - variant in parts of complex queries. Only the <literal>WITH</>, - <literal>UNION</>, <literal>INTERSECT</>, <literal>EXCEPT</>, - <literal>ORDER BY</>, <literal>LIMIT</>, <literal>OFFSET</>, - <literal>FETCH</> and <literal>FOR</> locking clauses can be used - with <command>TABLE</>; the <literal>WHERE</> clause and any form of + variant in parts of complex queries. Only the <literal>WITH</literal>, + <literal>UNION</literal>, <literal>INTERSECT</literal>, <literal>EXCEPT</literal>, + <literal>ORDER BY</literal>, <literal>LIMIT</literal>, <literal>OFFSET</literal>, + <literal>FETCH</literal> and <literal>FOR</literal> locking clauses can be used + with <command>TABLE</command>; the <literal>WHERE</literal> clause and any form of aggregation cannot be used. </para> @@ -1702,7 +1702,7 @@ SELECT actors.name </para> <para> - This example shows how to use a function in the <literal>FROM</> + This example shows how to use a function in the <literal>FROM</literal> clause, both with and without a column definition list: <programlisting> @@ -1744,7 +1744,7 @@ SELECT * FROM unnest(ARRAY['a','b','c','d','e','f']) WITH ORDINALITY; </para> <para> - This example shows how to use a simple <literal>WITH</> clause: + This example shows how to use a simple <literal>WITH</literal> clause: <programlisting> WITH t AS ( @@ -1764,7 +1764,7 @@ SELECT * FROM t 0.0735620250925422 </programlisting> - Notice that the <literal>WITH</> query was evaluated only once, + Notice that the <literal>WITH</literal> query was evaluated only once, so that we got two sets of the same three random values. </para> @@ -1796,9 +1796,9 @@ SELECT distance, employee_name FROM employee_recursive; </para> <para> - This example uses <literal>LATERAL</> to apply a set-returning function - <function>get_product_names()</> for each row of the - <structname>manufacturers</> table: + This example uses <literal>LATERAL</literal> to apply a set-returning function + <function>get_product_names()</function> for each row of the + <structname>manufacturers</structname> table: <programlisting> SELECT m.name AS mname, pname @@ -1866,7 +1866,7 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; This is not valid syntax according to the SQL standard. <productname>PostgreSQL</productname> allows it to be consistent with allowing zero-column tables. - However, an empty list is not allowed when <literal>DISTINCT</> is used. + However, an empty list is not allowed when <literal>DISTINCT</literal> is used. </para> </refsect2> @@ -1874,19 +1874,19 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; <title>Omitting the <literal>AS</literal> Key Word</title> <para> - In the SQL standard, the optional key word <literal>AS</> can be + In the SQL standard, the optional key word <literal>AS</literal> 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). <productname>PostgreSQL</productname> is slightly more - restrictive: <literal>AS</> is required if the new column name + restrictive: <literal>AS</literal> is required if the new column name matches any keyword at all, reserved or not. Recommended practice is - to use <literal>AS</> or double-quote output column names, to prevent + to use <literal>AS</literal> or double-quote output column names, to prevent any possible conflict against future keyword additions. </para> <para> In <literal>FROM</literal> items, both the standard and - <productname>PostgreSQL</productname> allow <literal>AS</> to + <productname>PostgreSQL</productname> allow <literal>AS</literal> to be omitted before an alias that is an unreserved keyword. But this is impractical for output column names, because of syntactic ambiguities. @@ -1899,12 +1899,12 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; <para> The SQL standard requires parentheses around the table name when writing <literal>ONLY</literal>, for example <literal>SELECT * FROM ONLY - (tab1), ONLY (tab2) WHERE ...</literal>. <productname>PostgreSQL</> + (tab1), ONLY (tab2) WHERE ...</literal>. <productname>PostgreSQL</productname> considers these parentheses to be optional. </para> <para> - <productname>PostgreSQL</> allows a trailing <literal>*</> to be written to + <productname>PostgreSQL</productname> allows a trailing <literal>*</literal> to be written to explicitly specify the non-<literal>ONLY</literal> behavior of including child tables. The standard does not allow this. </para> @@ -1919,9 +1919,9 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; <title><literal>TABLESAMPLE</literal> Clause Restrictions</title> <para> - The <literal>TABLESAMPLE</> clause is currently accepted only on + The <literal>TABLESAMPLE</literal> 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 <literal>FROM</> item. + it should be possible to apply it to any <literal>FROM</literal> item. </para> </refsect2> @@ -1930,16 +1930,16 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; <para> <productname>PostgreSQL</productname> allows a function call to be - written directly as a member of the <literal>FROM</> list. In the SQL + written directly as a member of the <literal>FROM</literal> list. In the SQL standard it would be necessary to wrap such a function call in a sub-<command>SELECT</command>; that is, the syntax - <literal>FROM <replaceable>func</>(...) <replaceable>alias</></literal> + <literal>FROM <replaceable>func</replaceable>(...) <replaceable>alias</replaceable></literal> is approximately equivalent to - <literal>FROM LATERAL (SELECT <replaceable>func</>(...)) <replaceable>alias</></literal>. - Note that <literal>LATERAL</> is considered to be implicit; this is - because the standard requires <literal>LATERAL</> semantics for an - <literal>UNNEST()</> item in <literal>FROM</>. - <productname>PostgreSQL</productname> treats <literal>UNNEST()</> the + <literal>FROM LATERAL (SELECT <replaceable>func</replaceable>(...)) <replaceable>alias</replaceable></literal>. + Note that <literal>LATERAL</literal> is considered to be implicit; this is + because the standard requires <literal>LATERAL</literal> semantics for an + <literal>UNNEST()</literal> item in <literal>FROM</literal>. + <productname>PostgreSQL</productname> treats <literal>UNNEST()</literal> the same as other set-returning functions. </para> </refsect2> @@ -1974,8 +1974,8 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; <para> <productname>PostgreSQL</productname> recognizes functional dependency - (allowing columns to be omitted from <literal>GROUP BY</>) only when - a table's primary key is included in the <literal>GROUP BY</> list. + (allowing columns to be omitted from <literal>GROUP BY</literal>) only when + a table's primary key is included in the <literal>GROUP BY</literal> list. The SQL standard specifies additional conditions that should be recognized. </para> @@ -1986,7 +1986,7 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; <para> The SQL standard provides additional options for the window - <replaceable class="parameter">frame_clause</>. + <replaceable class="parameter">frame_clause</replaceable>. <productname>PostgreSQL</productname> currently supports only the options listed above. </para> @@ -2011,26 +2011,26 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; </refsect2> <refsect2> - <title><literal>FOR NO KEY UPDATE</>, <literal>FOR UPDATE</>, <literal>FOR SHARE</>, <literal>FOR KEY SHARE</></title> + <title><literal>FOR NO KEY UPDATE</literal>, <literal>FOR UPDATE</literal>, <literal>FOR SHARE</literal>, <literal>FOR KEY SHARE</literal></title> <para> - Although <literal>FOR UPDATE</> appears in the SQL standard, the - standard allows it only as an option of <command>DECLARE CURSOR</>. - <productname>PostgreSQL</productname> allows it in any <command>SELECT</> - query as well as in sub-<command>SELECT</>s, but this is an extension. - The <literal>FOR NO KEY UPDATE</>, <literal>FOR SHARE</> and - <literal>FOR KEY SHARE</> variants, as well as the <literal>NOWAIT</> + Although <literal>FOR UPDATE</literal> appears in the SQL standard, the + standard allows it only as an option of <command>DECLARE CURSOR</command>. + <productname>PostgreSQL</productname> allows it in any <command>SELECT</command> + query as well as in sub-<command>SELECT</command>s, but this is an extension. + The <literal>FOR NO KEY UPDATE</literal>, <literal>FOR SHARE</literal> and + <literal>FOR KEY SHARE</literal> variants, as well as the <literal>NOWAIT</literal> and <literal>SKIP LOCKED</literal> options, do not appear in the standard. </para> </refsect2> <refsect2> - <title>Data-Modifying Statements in <literal>WITH</></title> + <title>Data-Modifying Statements in <literal>WITH</literal></title> <para> - <productname>PostgreSQL</productname> allows <command>INSERT</>, - <command>UPDATE</>, and <command>DELETE</> to be used as <literal>WITH</> + <productname>PostgreSQL</productname> allows <command>INSERT</command>, + <command>UPDATE</command>, and <command>DELETE</command> to be used as <literal>WITH</literal> queries. This is not found in the SQL standard. </para> </refsect2> @@ -2044,7 +2044,7 @@ SELECT distributors.* WHERE distributors.name = 'Westward'; </para> <para> - <literal>ROWS FROM( ... )</> is an extension of the SQL standard. + <literal>ROWS FROM( ... )</literal> is an extension of the SQL standard. </para> </refsect2> diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml index 89c0fad1950..8c44d0e156d 100644 --- a/doc/src/sgml/ref/set.sgml +++ b/doc/src/sgml/ref/set.sgml @@ -66,15 +66,15 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</rep <para> If <command>SET LOCAL</command> is used within a function that has a - <literal>SET</> option for the same variable (see + <literal>SET</literal> option for the same variable (see <xref linkend="sql-createfunction">), the effects of the <command>SET LOCAL</command> command disappear at function exit; that is, the value in effect when the function was called is restored anyway. This allows <command>SET LOCAL</command> to be used for dynamic or repeated changes of a parameter within a function, while still - having the convenience of using the <literal>SET</> option to save and - restore the caller's value. However, a regular <command>SET</> command - overrides any surrounding function's <literal>SET</> option; its effects + having the convenience of using the <literal>SET</literal> option to save and + restore the caller's value. However, a regular <command>SET</command> command + overrides any surrounding function's <literal>SET</literal> option; its effects will persist unless rolled back. </para> @@ -94,22 +94,22 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</rep <variablelist> <varlistentry> - <term><literal>SESSION</></term> + <term><literal>SESSION</literal></term> <listitem> <para> Specifies that the command takes effect for the current session. - (This is the default if neither <literal>SESSION</> nor - <literal>LOCAL</> appears.) + (This is the default if neither <literal>SESSION</literal> nor + <literal>LOCAL</literal> appears.) </para> </listitem> </varlistentry> <varlistentry> - <term><literal>LOCAL</></term> + <term><literal>LOCAL</literal></term> <listitem> <para> Specifies that the command takes effect for only the current - transaction. After <command>COMMIT</> or <command>ROLLBACK</>, + transaction. After <command>COMMIT</command> or <command>ROLLBACK</command>, the session-level setting takes effect again. Issuing this outside of a transaction block emits a warning and otherwise has no effect. @@ -136,7 +136,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</rep these, as appropriate for the particular parameter. <literal>DEFAULT</literal> can be written to specify resetting the parameter to its default value (that is, whatever - value it would have had if no <command>SET</> had been executed + value it would have had if no <command>SET</command> had been executed in the current session). </para> </listitem> @@ -153,8 +153,8 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</rep <varlistentry> <term><literal>SCHEMA</literal></term> <listitem> - <para><literal>SET SCHEMA '<replaceable>value</>'</> is an alias for - <literal>SET search_path TO <replaceable>value</></>. Only one + <para><literal>SET SCHEMA '<replaceable>value</replaceable>'</literal> is an alias for + <literal>SET search_path TO <replaceable>value</replaceable></literal>. Only one schema can be specified using this syntax. </para> </listitem> @@ -163,8 +163,8 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</rep <varlistentry> <term><literal>NAMES</literal></term> <listitem> - <para><literal>SET NAMES <replaceable>value</></> is an alias for - <literal>SET client_encoding TO <replaceable>value</></>. + <para><literal>SET NAMES <replaceable>value</replaceable></literal> is an alias for + <literal>SET client_encoding TO <replaceable>value</replaceable></literal>. </para> </listitem> </varlistentry> @@ -176,7 +176,7 @@ SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</rep Sets the internal seed for the random number generator (the function <function>random</function>). Allowed values are floating-point numbers between -1 and 1, which are then - multiplied by 2<superscript>31</>-1. + multiplied by 2<superscript>31</superscript>-1. </para> <para> @@ -191,8 +191,8 @@ SELECT setseed(<replaceable>value</replaceable>); <varlistentry> <term><literal>TIME ZONE</literal></term> <listitem> - <para><literal>SET TIME ZONE <replaceable>value</></> is an alias - for <literal>SET timezone TO <replaceable>value</></>. The + <para><literal>SET TIME ZONE <replaceable>value</replaceable></literal> is an alias + for <literal>SET timezone TO <replaceable>value</replaceable></literal>. The syntax <literal>SET TIME ZONE</literal> allows special syntax for the time zone specification. Here are examples of valid values: @@ -238,7 +238,7 @@ SELECT setseed(<replaceable>value</replaceable>); <listitem> <para> Set the time zone to your local time zone (that is, the - server's default value of <varname>timezone</>). + server's default value of <varname>timezone</varname>). </para> </listitem> </varlistentry> @@ -248,8 +248,8 @@ SELECT setseed(<replaceable>value</replaceable>); <para> Timezone settings given as numbers or intervals are internally translated to POSIX timezone syntax. For example, after - <literal>SET TIME ZONE -7</>, <command>SHOW TIME ZONE</> would - report <literal><-07>+07</>. + <literal>SET TIME ZONE -7</literal>, <command>SHOW TIME ZONE</command> would + report <literal><-07>+07</literal>. </para> <para> @@ -270,7 +270,7 @@ SELECT setseed(<replaceable>value</replaceable>); functionality; see <xref linkend="functions-admin">. Also, it is possible to UPDATE the <link linkend="view-pg-settings"><structname>pg_settings</structname></link> - system view to perform the equivalent of <command>SET</>. + system view to perform the equivalent of <command>SET</command>. </para> </refsect1> @@ -286,7 +286,7 @@ SET search_path TO my_schema, public; <para> Set the style of date to traditional - <productname>POSTGRES</productname> with <quote>day before month</> + <productname>POSTGRES</productname> with <quote>day before month</quote> input convention: <screen> SET datestyle TO postgres, dmy; diff --git a/doc/src/sgml/ref/set_constraints.sgml b/doc/src/sgml/ref/set_constraints.sgml index 7c31871b0bd..237a0a3988f 100644 --- a/doc/src/sgml/ref/set_constraints.sgml +++ b/doc/src/sgml/ref/set_constraints.sgml @@ -67,18 +67,18 @@ SET CONSTRAINTS { ALL | <replaceable class="parameter">name</replaceable> [, ... </para> <para> - Currently, only <literal>UNIQUE</>, <literal>PRIMARY KEY</>, - <literal>REFERENCES</> (foreign key), and <literal>EXCLUDE</> + Currently, only <literal>UNIQUE</literal>, <literal>PRIMARY KEY</literal>, + <literal>REFERENCES</literal> (foreign key), and <literal>EXCLUDE</literal> constraints are affected by this setting. - <literal>NOT NULL</> and <literal>CHECK</> constraints are + <literal>NOT NULL</literal> and <literal>CHECK</literal> constraints are always checked immediately when a row is inserted or modified - (<emphasis>not</> at the end of the statement). + (<emphasis>not</emphasis> at the end of the statement). Uniqueness and exclusion constraints that have not been declared - <literal>DEFERRABLE</> are also checked immediately. + <literal>DEFERRABLE</literal> are also checked immediately. </para> <para> - The firing of triggers that are declared as <quote>constraint triggers</> + The firing of triggers that are declared as <quote>constraint triggers</quote> is also controlled by this setting — they fire at the same time that the associated constraint should be checked. </para> @@ -111,7 +111,7 @@ SET CONSTRAINTS { ALL | <replaceable class="parameter">name</replaceable> [, ... This command complies with the behavior defined in the SQL standard, except for the limitation that, in <productname>PostgreSQL</productname>, it does not apply to - <literal>NOT NULL</> and <literal>CHECK</> constraints. + <literal>NOT NULL</literal> and <literal>CHECK</literal> constraints. Also, <productname>PostgreSQL</productname> checks non-deferrable uniqueness constraints immediately, not at end of statement as the standard would suggest. diff --git a/doc/src/sgml/ref/set_role.sgml b/doc/src/sgml/ref/set_role.sgml index a97ceabcff8..eac4b3405ae 100644 --- a/doc/src/sgml/ref/set_role.sgml +++ b/doc/src/sgml/ref/set_role.sgml @@ -35,7 +35,7 @@ RESET ROLE identifier of the current SQL session to be <replaceable class="parameter">role_name</replaceable>. The role name can be written as either an identifier or a string literal. - After <command>SET ROLE</>, permissions checking for SQL commands + After <command>SET ROLE</command>, permissions checking for SQL commands is carried out as though the named role were the one that had logged in originally. </para> @@ -47,13 +47,13 @@ RESET ROLE </para> <para> - The <literal>SESSION</> and <literal>LOCAL</> modifiers act the same + The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers act the same as for the regular <xref linkend="SQL-SET"> command. </para> <para> - The <literal>NONE</> and <literal>RESET</> forms reset the current + The <literal>NONE</literal> and <literal>RESET</literal> forms reset the current user identifier to be the current session user identifier. These forms can be executed by any user. </para> @@ -64,41 +64,41 @@ RESET ROLE <para> Using this command, it is possible to either add privileges or restrict - one's privileges. If the session user role has the <literal>INHERITS</> + one's privileges. If the session user role has the <literal>INHERITS</literal> attribute, then it automatically has all the privileges of every role that - it could <command>SET ROLE</> to; in this case <command>SET ROLE</> + it could <command>SET ROLE</command> to; in this case <command>SET ROLE</command> 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 <literal>NOINHERITS</> attribute, <command>SET ROLE</> drops the + has the <literal>NOINHERITS</literal> attribute, <command>SET ROLE</command> drops the privileges assigned directly to the session user and instead acquires the privileges available to the named role. </para> <para> - In particular, when a superuser chooses to <command>SET ROLE</> to a + In particular, when a superuser chooses to <command>SET ROLE</command> to a non-superuser role, they lose their superuser privileges. </para> <para> - <command>SET ROLE</> has effects comparable to + <command>SET ROLE</command> has effects comparable to <xref linkend="sql-set-session-authorization">, but the privilege checks involved are quite different. Also, - <command>SET SESSION AUTHORIZATION</> determines which roles are - allowable for later <command>SET ROLE</> commands, whereas changing - roles with <command>SET ROLE</> does not change the set of roles - allowed to a later <command>SET ROLE</>. + <command>SET SESSION AUTHORIZATION</command> determines which roles are + allowable for later <command>SET ROLE</command> commands, whereas changing + roles with <command>SET ROLE</command> does not change the set of roles + allowed to a later <command>SET ROLE</command>. </para> <para> - <command>SET ROLE</> does not process session variables as specified by + <command>SET ROLE</command> does not process session variables as specified by the role's <xref linkend="sql-alterrole"> settings; this only happens during login. </para> <para> - <command>SET ROLE</> cannot be used within a - <literal>SECURITY DEFINER</> function. + <command>SET ROLE</command> cannot be used within a + <literal>SECURITY DEFINER</literal> function. </para> </refsect1> @@ -127,14 +127,14 @@ SELECT SESSION_USER, CURRENT_USER; <para> <productname>PostgreSQL</productname> - allows identifier syntax (<literal>"<replaceable>rolename</>"</literal>), while + allows identifier syntax (<literal>"<replaceable>rolename</replaceable>"</literal>), while the SQL standard requires the role name to be written as a string literal. SQL does not allow this command during a transaction; <productname>PostgreSQL</productname> does not make this restriction because there is no reason to. - The <literal>SESSION</> and <literal>LOCAL</> modifiers are a + The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers are a <productname>PostgreSQL</productname> extension, as is the - <literal>RESET</> syntax. + <literal>RESET</literal> syntax. </para> </refsect1> diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml index 96d279aaf94..a8aee6f6323 100644 --- a/doc/src/sgml/ref/set_session_auth.sgml +++ b/doc/src/sgml/ref/set_session_auth.sgml @@ -39,7 +39,7 @@ RESET SESSION AUTHORIZATION 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 <literal>SECURITY DEFINER</> + might change temporarily in the context of <literal>SECURITY DEFINER</literal> functions and similar mechanisms; it can also be changed by <xref linkend="sql-set-role">. The current user identifier is relevant for permission checking. @@ -53,13 +53,13 @@ RESET SESSION AUTHORIZATION </para> <para> - The <literal>SESSION</> and <literal>LOCAL</> modifiers act the same + The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers act the same as for the regular <xref linkend="SQL-SET"> command. </para> <para> - The <literal>DEFAULT</> and <literal>RESET</> forms reset the session + The <literal>DEFAULT</literal> and <literal>RESET</literal> forms reset the session and current user identifiers to be the originally authenticated user name. These forms can be executed by any user. </para> @@ -69,8 +69,8 @@ RESET SESSION AUTHORIZATION <title>Notes</title> <para> - <command>SET SESSION AUTHORIZATION</> cannot be used within a - <literal>SECURITY DEFINER</> function. + <command>SET SESSION AUTHORIZATION</command> cannot be used within a + <literal>SECURITY DEFINER</literal> function. </para> </refsect1> @@ -101,13 +101,13 @@ SELECT SESSION_USER, CURRENT_USER; The SQL standard allows some other expressions to appear in place of the literal <replaceable>user_name</replaceable>, but these options are not important in practice. <productname>PostgreSQL</productname> - allows identifier syntax (<literal>"<replaceable>username</>"</literal>), which SQL + allows identifier syntax (<literal>"<replaceable>username</replaceable>"</literal>), which SQL does not. SQL does not allow this command during a transaction; <productname>PostgreSQL</productname> does not make this restriction because there is no reason to. - The <literal>SESSION</> and <literal>LOCAL</> modifiers are a + The <literal>SESSION</literal> and <literal>LOCAL</literal> modifiers are a <productname>PostgreSQL</productname> extension, as is the - <literal>RESET</> syntax. + <literal>RESET</literal> syntax. </para> <para> diff --git a/doc/src/sgml/ref/set_transaction.sgml b/doc/src/sgml/ref/set_transaction.sgml index 188d2ed92ea..f5631372f56 100644 --- a/doc/src/sgml/ref/set_transaction.sgml +++ b/doc/src/sgml/ref/set_transaction.sgml @@ -153,14 +153,14 @@ SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transa <para> The <literal>SET TRANSACTION SNAPSHOT</literal> command allows a new - transaction to run with the same <firstterm>snapshot</> as an existing + transaction to run with the same <firstterm>snapshot</firstterm> as an existing transaction. The pre-existing transaction must have exported its snapshot with the <literal>pg_export_snapshot</literal> function (see <xref linkend="functions-snapshot-synchronization">). That function returns a snapshot identifier, which must be given to <literal>SET TRANSACTION SNAPSHOT</literal> to specify which snapshot is to be imported. The identifier must be written as a string literal in this command, for example - <literal>'000003A1-1'</>. + <literal>'000003A1-1'</literal>. <literal>SET TRANSACTION SNAPSHOT</literal> can only be executed at the start of a transaction, before the first query or data-modification statement (<command>SELECT</command>, @@ -169,7 +169,7 @@ SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transa <command>COPY</command>) of the transaction. Furthermore, the transaction must already be set to <literal>SERIALIZABLE</literal> or <literal>REPEATABLE READ</literal> isolation level (otherwise, the snapshot - would be discarded immediately, since <literal>READ COMMITTED</> mode takes + would be discarded immediately, since <literal>READ COMMITTED</literal> mode takes a new snapshot for each command). If the importing transaction uses <literal>SERIALIZABLE</literal> isolation level, then the transaction that exported the snapshot must also use that isolation level. Also, a @@ -203,9 +203,9 @@ SET SESSION CHARACTERISTICS AS TRANSACTION <replaceable class="parameter">transa <xref linkend="guc-default-transaction-read-only">, and <xref linkend="guc-default-transaction-deferrable">. (In fact <command>SET SESSION CHARACTERISTICS</command> is just a - verbose equivalent for setting these variables with <command>SET</>.) + verbose equivalent for setting these variables with <command>SET</command>.) This means the defaults can be set in the configuration file, via - <command>ALTER DATABASE</>, etc. Consult <xref linkend="runtime-config"> + <command>ALTER DATABASE</command>, etc. Consult <xref linkend="runtime-config"> for more information. </para> </refsect1> @@ -243,7 +243,7 @@ SET TRANSACTION SNAPSHOT '00000003-0000001B-1'; <para> These commands are defined in the <acronym>SQL</acronym> standard, except for the <literal>DEFERRABLE</literal> transaction mode - and the <command>SET TRANSACTION SNAPSHOT</> form, which are + and the <command>SET TRANSACTION SNAPSHOT</command> form, which are <productname>PostgreSQL</productname> extensions. </para> diff --git a/doc/src/sgml/ref/show.sgml b/doc/src/sgml/ref/show.sgml index 7e198e6df8c..2a2b2fbb9f3 100644 --- a/doc/src/sgml/ref/show.sgml +++ b/doc/src/sgml/ref/show.sgml @@ -35,7 +35,7 @@ SHOW ALL <command>SET</command> statement, by editing the <filename>postgresql.conf</filename> configuration file, through the <envar>PGOPTIONS</envar> environmental variable (when using - <application>libpq</> or a <application>libpq</>-based + <application>libpq</application> or a <application>libpq</application>-based application), or through command-line flags when starting the <command>postgres</command> server. See <xref linkend="runtime-config"> for details. diff --git a/doc/src/sgml/ref/start_transaction.sgml b/doc/src/sgml/ref/start_transaction.sgml index 60926f5dfef..8dcf6318d23 100644 --- a/doc/src/sgml/ref/start_transaction.sgml +++ b/doc/src/sgml/ref/start_transaction.sgml @@ -55,12 +55,12 @@ START TRANSACTION [ <replaceable class="parameter">transaction_mode</replaceable <title>Compatibility</title> <para> - In the standard, it is not necessary to issue <command>START TRANSACTION</> + In the standard, it is not necessary to issue <command>START TRANSACTION</command> to start a transaction block: any SQL command implicitly begins a block. <productname>PostgreSQL</productname>'s behavior can be seen as implicitly issuing a <command>COMMIT</command> after each command that does not - follow <command>START TRANSACTION</> (or <command>BEGIN</command>), - and it is therefore often called <quote>autocommit</>. + follow <command>START TRANSACTION</command> (or <command>BEGIN</command>), + and it is therefore often called <quote>autocommit</quote>. Other relational database systems might offer an autocommit feature as a convenience. </para> diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml index fef33155998..80abe675253 100644 --- a/doc/src/sgml/ref/truncate.sgml +++ b/doc/src/sgml/ref/truncate.sgml @@ -48,9 +48,9 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ <listitem> <para> The name (optionally schema-qualified) of a table to truncate. - If <literal>ONLY</> is specified before the table name, only that table - is truncated. If <literal>ONLY</> is not specified, the table and all - its descendant tables (if any) are truncated. Optionally, <literal>*</> + If <literal>ONLY</literal> is specified before the table name, only that table + is truncated. If <literal>ONLY</literal> is not specified, the table and all + its descendant tables (if any) are truncated. Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> @@ -108,29 +108,29 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ </para> <para> - <command>TRUNCATE</> acquires an <literal>ACCESS EXCLUSIVE</> lock on each + <command>TRUNCATE</command> acquires an <literal>ACCESS EXCLUSIVE</literal> lock on each table it operates on, which blocks all other concurrent operations - on the table. When <literal>RESTART IDENTITY</> is specified, any + on the table. When <literal>RESTART IDENTITY</literal> is specified, any sequences that are to be restarted are likewise locked exclusively. If concurrent access to a table is required, then - the <command>DELETE</> command should be used instead. + the <command>DELETE</command> command should be used instead. </para> <para> - <command>TRUNCATE</> cannot be used on a table that has foreign-key + <command>TRUNCATE</command> 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 <literal>CASCADE</> + scans, and the whole point is not to do one. The <literal>CASCADE</literal> option can be used to automatically include all dependent tables — but be very careful when using this option, or else you might lose data you did not intend to! </para> <para> - <command>TRUNCATE</> will not fire any <literal>ON DELETE</literal> + <command>TRUNCATE</command> will not fire any <literal>ON DELETE</literal> triggers that might exist for the tables. But it will fire <literal>ON TRUNCATE</literal> triggers. - If <literal>ON TRUNCATE</> triggers are defined for any of + If <literal>ON TRUNCATE</literal> triggers are defined for any of the tables, then all <literal>BEFORE TRUNCATE</literal> triggers are fired before any truncation happens, and all <literal>AFTER TRUNCATE</literal> triggers are fired after the last truncation is @@ -141,36 +141,36 @@ TRUNCATE [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ </para> <para> - <command>TRUNCATE</> is not MVCC-safe. After truncation, the table will + <command>TRUNCATE</command> 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 <xref linkend="mvcc-caveats"> for more details. </para> <para> - <command>TRUNCATE</> is transaction-safe with respect to the data + <command>TRUNCATE</command> 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. </para> <para> - When <literal>RESTART IDENTITY</> is specified, the implied - <command>ALTER SEQUENCE RESTART</> operations are also done + When <literal>RESTART IDENTITY</literal> is specified, the implied + <command>ALTER SEQUENCE RESTART</command> operations are also done transactionally; that is, they will be rolled back if the surrounding transaction does not commit. This is unlike the normal behavior of - <command>ALTER SEQUENCE RESTART</>. Be aware that if any additional + <command>ALTER SEQUENCE RESTART</command>. 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 <function>currval()</>; - that is, after the transaction <function>currval()</> will continue to + will be rolled back, but not their effects on <function>currval()</function>; + that is, after the transaction <function>currval()</function> 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 <function>currval()</> after + This is similar to the usual behavior of <function>currval()</function> after a failed transaction. </para> <para> - <command>TRUNCATE</> is not currently supported for foreign tables. + <command>TRUNCATE</command> is not currently supported for foreign tables. This implies that if a specified table has any descendant tables that are foreign, the command will fail. </para> diff --git a/doc/src/sgml/ref/unlisten.sgml b/doc/src/sgml/ref/unlisten.sgml index 622e1cf1548..1ea9aa3a0bd 100644 --- a/doc/src/sgml/ref/unlisten.sgml +++ b/doc/src/sgml/ref/unlisten.sgml @@ -104,7 +104,7 @@ Asynchronous notification "virtual" received from server process with PID 8448. </para> <para> - Once <command>UNLISTEN</> has been executed, further <command>NOTIFY</> + Once <command>UNLISTEN</command> has been executed, further <command>NOTIFY</command> messages will be ignored: <programlisting> diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml index 9dcbbd0e287..1ede52384f3 100644 --- a/doc/src/sgml/ref/update.sgml +++ b/doc/src/sgml/ref/update.sgml @@ -52,13 +52,13 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ </para> <para> - The optional <literal>RETURNING</> clause causes <command>UPDATE</> + The optional <literal>RETURNING</literal> clause causes <command>UPDATE</command> to compute and return value(s) based on each row actually updated. Any expression using the table's columns, and/or columns of other tables mentioned in <literal>FROM</literal>, can be computed. The new (post-update) values of the table's columns are used. - The syntax of the <literal>RETURNING</> list is identical to that of the - output list of <command>SELECT</>. + The syntax of the <literal>RETURNING</literal> list is identical to that of the + output list of <command>SELECT</command>. </para> <para> @@ -80,7 +80,7 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <listitem> <para> The <literal>WITH</literal> clause allows you to specify one or more - subqueries that can be referenced by name in the <command>UPDATE</> + subqueries that can be referenced by name in the <command>UPDATE</command> query. See <xref linkend="queries-with"> and <xref linkend="sql-select"> for details. </para> @@ -92,10 +92,10 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <listitem> <para> The name (optionally schema-qualified) of the table to update. - If <literal>ONLY</> is specified before the table name, matching rows - are updated in the named table only. If <literal>ONLY</> is not + If <literal>ONLY</literal> is specified before the table name, matching rows + are updated in the named table only. If <literal>ONLY</literal> is not specified, matching rows are also updated in any tables inheriting from - the named table. Optionally, <literal>*</> can be specified after the + the named table. Optionally, <literal>*</literal> can be specified after the table name to explicitly indicate that descendant tables are included. </para> </listitem> @@ -107,9 +107,9 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <para> A substitute name for the target table. When an alias is provided, it completely hides the actual name of the table. For - example, given <literal>UPDATE foo AS f</>, the remainder of the + example, given <literal>UPDATE foo AS f</literal>, the remainder of the <command>UPDATE</command> statement must refer to this table as - <literal>f</> not <literal>foo</>. + <literal>f</literal> not <literal>foo</literal>. </para> </listitem> </varlistentry> @@ -123,7 +123,7 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ The column name can be qualified with a subfield name or array subscript, if needed. Do not include the table's name in the specification of a target column — for example, - <literal>UPDATE table_name SET table_name.col = 1</> is invalid. + <literal>UPDATE table_name SET table_name.col = 1</literal> is invalid. </para> </listitem> </varlistentry> @@ -152,7 +152,7 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <term><replaceable class="parameter">sub-SELECT</replaceable></term> <listitem> <para> - A <literal>SELECT</> sub-query that produces as many output columns + A <literal>SELECT</literal> 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; @@ -168,13 +168,13 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <listitem> <para> A list of table expressions, allowing columns from other tables - to appear in the <literal>WHERE</> condition and the update + to appear in the <literal>WHERE</literal> condition and the update expressions. This is similar to the list of tables that can be specified in the <xref linkend="sql-from" endterm="sql-from-title"> of a <command>SELECT</command> statement. Note that the target table must not appear in the - <replaceable>from_list</>, unless you intend a self-join (in which - case it must appear with an alias in the <replaceable>from_list</>). + <replaceable>from_list</replaceable>, unless you intend a self-join (in which + case it must appear with an alias in the <replaceable>from_list</replaceable>). </para> </listitem> </varlistentry> @@ -184,7 +184,7 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <listitem> <para> An expression that returns a value of type <type>boolean</type>. - Only rows for which this expression returns <literal>true</> + Only rows for which this expression returns <literal>true</literal> will be updated. </para> </listitem> @@ -194,15 +194,15 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <term><replaceable class="parameter">cursor_name</replaceable></term> <listitem> <para> - The name of the cursor to use in a <literal>WHERE CURRENT OF</> + The name of the cursor to use in a <literal>WHERE CURRENT OF</literal> 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 <command>UPDATE</>'s target table. - Note that <literal>WHERE CURRENT OF</> cannot be + query on the <command>UPDATE</command>'s target table. + Note that <literal>WHERE CURRENT OF</literal> cannot be specified together with a Boolean condition. See <xref linkend="sql-declare"> for more information about using cursors with - <literal>WHERE CURRENT OF</>. + <literal>WHERE CURRENT OF</literal>. </para> </listitem> </varlistentry> @@ -211,11 +211,11 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <term><replaceable class="parameter">output_expression</replaceable></term> <listitem> <para> - An expression to be computed and returned by the <command>UPDATE</> + An expression to be computed and returned by the <command>UPDATE</command> command after each row is updated. The expression can use any column names of the table named by <replaceable class="parameter">table_name</replaceable> - or table(s) listed in <literal>FROM</>. - Write <literal>*</> to return all columns. + or table(s) listed in <literal>FROM</literal>. + Write <literal>*</literal> to return all columns. </para> </listitem> </varlistentry> @@ -235,7 +235,7 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [ <title>Outputs</title> <para> - On successful completion, an <command>UPDATE</> command returns a command + On successful completion, an <command>UPDATE</command> command returns a command tag of the form <screen> UPDATE <replaceable class="parameter">count</replaceable> @@ -244,16 +244,16 @@ UPDATE <replaceable class="parameter">count</replaceable> 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 <replaceable class="parameter">condition</replaceable> when - updates were suppressed by a <literal>BEFORE UPDATE</> trigger. If + updates were suppressed by a <literal>BEFORE UPDATE</literal> trigger. If <replaceable class="parameter">count</replaceable> is 0, no rows were updated by the query (this is not considered an error). </para> <para> - If the <command>UPDATE</> command contains a <literal>RETURNING</> - clause, the result will be similar to that of a <command>SELECT</> + If the <command>UPDATE</command> command contains a <literal>RETURNING</literal> + clause, the result will be similar to that of a <command>SELECT</command> statement containing the columns and values defined in the - <literal>RETURNING</> list, computed over the row(s) updated by the + <literal>RETURNING</literal> list, computed over the row(s) updated by the command. </para> </refsect1> @@ -262,11 +262,11 @@ UPDATE <replaceable class="parameter">count</replaceable> <title>Notes</title> <para> - When a <literal>FROM</> clause is present, what essentially happens + When a <literal>FROM</literal> clause is present, what essentially happens is that the target table is joined to the tables mentioned in the <replaceable>from_list</replaceable>, and each output row of the join represents an update operation for the target table. When using - <literal>FROM</> you should ensure that the join + <literal>FROM</literal> 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't join to more than one row from the other table(s). If it does, then only one of the join rows @@ -293,8 +293,8 @@ UPDATE <replaceable class="parameter">count</replaceable> <title>Examples</title> <para> - Change the word <literal>Drama</> to <literal>Dramatic</> in the - column <structfield>kind</> of the table <structname>films</structname>: + Change the word <literal>Drama</literal> to <literal>Dramatic</literal> in the + column <structfield>kind</structfield> of the table <structname>films</structname>: <programlisting> UPDATE films SET kind = 'Dramatic' WHERE kind = 'Drama'; @@ -364,10 +364,10 @@ UPDATE accounts SET contact_first_name = first_name, FROM salesmen WHERE salesmen.id = accounts.sales_id; </programlisting> However, the second query may give unexpected results - if <structname>salesmen</>.<structfield>id</> is not a unique key, whereas + if <structname>salesmen</structname>.<structfield>id</structfield> is not a unique key, whereas the first query is guaranteed to raise an error if there are multiple - <structfield>id</> matches. Also, if there is no match for a particular - <structname>accounts</>.<structfield>sales_id</> entry, the first query + <structfield>id</structfield> matches. Also, if there is no match for a particular + <structname>accounts</structname>.<structfield>sales_id</structfield> entry, the first query will set the corresponding name fields to NULL, whereas the second query will not update that row at all. </para> @@ -400,9 +400,9 @@ COMMIT; </para> <para> - Change the <structfield>kind</> column of the table + Change the <structfield>kind</structfield> column of the table <structname>films</structname> in the row on which the cursor - <literal>c_films</> is currently positioned: + <literal>c_films</literal> is currently positioned: <programlisting> UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films; </programlisting></para> @@ -413,16 +413,16 @@ UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films; <para> This command conforms to the <acronym>SQL</acronym> standard, except - that the <literal>FROM</literal> and <literal>RETURNING</> clauses + that the <literal>FROM</literal> and <literal>RETURNING</literal> clauses are <productname>PostgreSQL</productname> extensions, as is the ability - to use <literal>WITH</> with <command>UPDATE</>. + to use <literal>WITH</literal> with <command>UPDATE</command>. </para> <para> - Some other database systems offer a <literal>FROM</> option in which - the target table is supposed to be listed again within <literal>FROM</>. + Some other database systems offer a <literal>FROM</literal> option in which + the target table is supposed to be listed again within <literal>FROM</literal>. That is not how <productname>PostgreSQL</productname> interprets - <literal>FROM</>. Be careful when porting applications that use this + <literal>FROM</literal>. Be careful when porting applications that use this extension. </para> @@ -431,9 +431,9 @@ UPDATE films SET kind = 'Dramatic' WHERE CURRENT OF c_films; target column names can be any row-valued expression yielding the correct number of columns. <productname>PostgreSQL</productname> only allows the source value to be a <link linkend="sql-syntax-row-constructors">row - constructor</link> or a sub-<literal>SELECT</>. An individual column's - updated value can be specified as <literal>DEFAULT</> in the - row-constructor case, but not inside a sub-<literal>SELECT</>. + constructor</link> or a sub-<literal>SELECT</literal>. An individual column's + updated value can be specified as <literal>DEFAULT</literal> in the + row-constructor case, but not inside a sub-<literal>SELECT</literal>. </para> </refsect1> </refentry> diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index f5bc87e2903..2e205668c1c 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -66,7 +66,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet </para> <para> - Plain <command>VACUUM</command> (without <literal>FULL</>) simply reclaims + Plain <command>VACUUM</command> (without <literal>FULL</literal>) 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 @@ -116,7 +116,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet <xref linkend="guc-vacuum-freeze-min-age"> and <xref linkend="guc-vacuum-freeze-table-age"> parameters set to zero. Aggressive freezing is always performed when the - table is rewritten, so this option is redundant when <literal>FULL</> + table is rewritten, so this option is redundant when <literal>FULL</literal> is specified. </para> </listitem> @@ -145,8 +145,8 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet <term><literal>DISABLE_PAGE_SKIPPING</literal></term> <listitem> <para> - Normally, <command>VACUUM</> will skip pages based on the <link - linkend="vacuum-for-visibility-map">visibility map</>. Pages where + Normally, <command>VACUUM</command> will skip pages based on the <link + linkend="vacuum-for-visibility-map">visibility map</link>. 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, @@ -176,7 +176,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet <listitem> <para> The name of a specific column to analyze. Defaults to all columns. - If a column list is specified, <literal>ANALYZE</> must also be + If a column list is specified, <literal>ANALYZE</literal> must also be specified. </para> </listitem> @@ -188,7 +188,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet <title>Outputs</title> <para> - When <literal>VERBOSE</> is specified, <command>VACUUM</> emits + When <literal>VERBOSE</literal> is specified, <command>VACUUM</command> emits progress messages to indicate which table is currently being processed. Various statistics about the tables are printed as well. </para> @@ -202,19 +202,19 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet 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 - <command>VACUUM</> can only be performed by a superuser.) - <command>VACUUM</> will skip over any tables that the calling user + <command>VACUUM</command> can only be performed by a superuser.) + <command>VACUUM</command> will skip over any tables that the calling user does not have permission to vacuum. </para> <para> - <command>VACUUM</> cannot be executed inside a transaction block. + <command>VACUUM</command> cannot be executed inside a transaction block. </para> <para> - For tables with <acronym>GIN</> indexes, <command>VACUUM</command> (in + For tables with <acronym>GIN</acronym> indexes, <command>VACUUM</command> (in any form) also completes any pending index insertions, by moving pending - index entries to the appropriate places in the main <acronym>GIN</> index + index entries to the appropriate places in the main <acronym>GIN</acronym> index structure. See <xref linkend="gin-fast-update"> for details. </para> @@ -247,7 +247,7 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ <replaceable class="paramet </para> <para> - <productname>PostgreSQL</productname> includes an <quote>autovacuum</> + <productname>PostgreSQL</productname> includes an <quote>autovacuum</quote> facility which can automate routine vacuum maintenance. For more information about automatic and manual vacuuming, see <xref linkend="routine-vacuuming">. diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 4f6fa0d7085..277c231687b 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -88,8 +88,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term> - <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></option></term> + <term><option><optional>-d</optional> <replaceable class="parameter">dbname</replaceable></option></term> + <term><option><optional>--dbname=</optional><replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to be cleaned or analyzed. @@ -103,8 +103,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-e</></term> - <term><option>--echo</></term> + <term><option>-e</option></term> + <term><option>--echo</option></term> <listitem> <para> Echo the commands that <application>vacuumdb</application> generates @@ -158,8 +158,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-q</></term> - <term><option>--quiet</></term> + <term><option>-q</option></term> + <term><option>--quiet</option></term> <listitem> <para> Do not display progress messages. @@ -176,7 +176,7 @@ PostgreSQL documentation Column names can be specified only in conjunction with the <option>--analyze</option> or <option>--analyze-only</option> options. Multiple tables can be vacuumed by writing multiple - <option>-t</> switches. + <option>-t</option> switches. </para> <tip> <para> @@ -198,8 +198,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-V</></term> - <term><option>--version</></term> + <term><option>-V</option></term> + <term><option>--version</option></term> <listitem> <para> Print the <application>vacuumdb</application> version and exit. @@ -248,8 +248,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-?</></term> - <term><option>--help</></term> + <term><option>-?</option></term> + <term><option>--help</option></term> <listitem> <para> Show help about <application>vacuumdb</application> command line @@ -266,8 +266,8 @@ PostgreSQL documentation the following command-line arguments for connection parameters: <variablelist> <varlistentry> - <term><option>-h <replaceable class="parameter">host</replaceable></></term> - <term><option>--host=<replaceable class="parameter">host</replaceable></></term> + <term><option>-h <replaceable class="parameter">host</replaceable></option></term> + <term><option>--host=<replaceable class="parameter">host</replaceable></option></term> <listitem> <para> Specifies the host name of the machine on which the server @@ -278,8 +278,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-p <replaceable class="parameter">port</replaceable></></term> - <term><option>--port=<replaceable class="parameter">port</replaceable></></term> + <term><option>-p <replaceable class="parameter">port</replaceable></option></term> + <term><option>--port=<replaceable class="parameter">port</replaceable></option></term> <listitem> <para> Specifies the TCP port or local Unix domain socket file @@ -290,8 +290,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-U <replaceable class="parameter">username</replaceable></></term> - <term><option>--username=<replaceable class="parameter">username</replaceable></></term> + <term><option>-U <replaceable class="parameter">username</replaceable></option></term> + <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> <listitem> <para> User name to connect as. @@ -300,8 +300,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-w</></term> - <term><option>--no-password</></term> + <term><option>-w</option></term> + <term><option>--no-password</option></term> <listitem> <para> Never issue a password prompt. If the server requires @@ -315,8 +315,8 @@ PostgreSQL documentation </varlistentry> <varlistentry> - <term><option>-W</></term> - <term><option>--password</></term> + <term><option>-W</option></term> + <term><option>--password</option></term> <listitem> <para> Force <application>vacuumdb</application> to prompt for a @@ -329,14 +329,14 @@ PostgreSQL documentation for a password if the server demands password authentication. However, <application>vacuumdb</application> will waste a connection attempt finding out that the server wants a password. - In some cases it is worth typing <option>-W</> to avoid the extra + In some cases it is worth typing <option>-W</option> to avoid the extra connection attempt. </para> </listitem> </varlistentry> <varlistentry> - <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term> + <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term> <listitem> <para> Specifies the name of the database to connect to discover what other @@ -370,8 +370,8 @@ PostgreSQL documentation </variablelist> <para> - This utility, like most other <productname>PostgreSQL</> utilities, - also uses the environment variables supported by <application>libpq</> + This utility, like most other <productname>PostgreSQL</productname> utilities, + also uses the environment variables supported by <application>libpq</application> (see <xref linkend="libpq-envars">). </para> @@ -401,7 +401,7 @@ PostgreSQL documentation <application>vacuumdb</application> might need to connect several times to the <productname>PostgreSQL</productname> server, asking for a password each time. It is convenient to have a - <filename>~/.pgpass</> file in such cases. See <xref + <filename>~/.pgpass</filename> file in such cases. See <xref linkend="libpq-pgpass"> for more information. </para> </refsect1> diff --git a/doc/src/sgml/ref/values.sgml b/doc/src/sgml/ref/values.sgml index 9baeade5519..75a594725b8 100644 --- a/doc/src/sgml/ref/values.sgml +++ b/doc/src/sgml/ref/values.sgml @@ -35,7 +35,7 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, .. <para> <command>VALUES</command> computes a row value or set of row values specified by value expressions. It is most commonly used to generate - a <quote>constant table</> within a larger command, but it can be + a <quote>constant table</quote> within a larger command, but it can be used on its own. </para> @@ -43,18 +43,18 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, .. When more than one row is specified, all the rows must have the same number of elements. The data types of the resulting table's columns are determined by combining the explicit or inferred types of the expressions - appearing in that column, using the same rules as for <literal>UNION</> + appearing in that column, using the same rules as for <literal>UNION</literal> (see <xref linkend="typeconv-union-case">). </para> <para> - Within larger commands, <command>VALUES</> is syntactically allowed - anywhere that <command>SELECT</> is. Because it is treated like a - <command>SELECT</> by the grammar, it is possible to use - the <literal>ORDER BY</>, <literal>LIMIT</> (or + Within larger commands, <command>VALUES</command> is syntactically allowed + anywhere that <command>SELECT</command> is. Because it is treated like a + <command>SELECT</command> by the grammar, it is possible to use + the <literal>ORDER BY</literal>, <literal>LIMIT</literal> (or equivalently <literal>FETCH FIRST</literal>), - and <literal>OFFSET</> clauses with a - <command>VALUES</> command. + and <literal>OFFSET</literal> clauses with a + <command>VALUES</command> command. </para> </refsect1> @@ -67,12 +67,12 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, .. <listitem> <para> A constant or expression to compute and insert at the indicated place - in the resulting table (set of rows). In a <command>VALUES</> list - appearing at the top level of an <command>INSERT</>, an + in the resulting table (set of rows). In a <command>VALUES</command> list + appearing at the top level of an <command>INSERT</command>, an <replaceable class="parameter">expression</replaceable> can be replaced by <literal>DEFAULT</literal> to indicate that the destination column's default value should be inserted. <literal>DEFAULT</literal> cannot - be used when <command>VALUES</> appears in other contexts. + be used when <command>VALUES</command> appears in other contexts. </para> </listitem> </varlistentry> @@ -83,7 +83,7 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, .. <para> An expression or integer constant indicating how to sort the result rows. This expression can refer to the columns of the - <command>VALUES</> result as <literal>column1</>, <literal>column2</>, + <command>VALUES</command> result as <literal>column1</literal>, <literal>column2</literal>, etc. For more details see <xref linkend="sql-orderby" endterm="sql-orderby-title">. </para> @@ -127,11 +127,11 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, .. <title>Notes</title> <para> - <command>VALUES</> lists with very large numbers of rows should be avoided, + <command>VALUES</command> lists with very large numbers of rows should be avoided, as you might encounter out-of-memory failures or poor performance. - <command>VALUES</> appearing within <command>INSERT</> is a special case - (because the desired column types are known from the <command>INSERT</>'s - target table, and need not be inferred by scanning the <command>VALUES</> + <command>VALUES</command> appearing within <command>INSERT</command> is a special case + (because the desired column types are known from the <command>INSERT</command>'s + target table, and need not be inferred by scanning the <command>VALUES</command> list), so it can handle larger lists than are practical in other contexts. </para> </refsect1> @@ -140,7 +140,7 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, .. <title>Examples</title> <para> - A bare <command>VALUES</> command: + A bare <command>VALUES</command> command: <programlisting> VALUES (1, 'one'), (2, 'two'), (3, 'three'); @@ -160,8 +160,8 @@ SELECT 3, 'three'; </para> <para> - More usually, <command>VALUES</> is used within a larger SQL command. - The most common use is in <command>INSERT</>: + More usually, <command>VALUES</command> is used within a larger SQL command. + The most common use is in <command>INSERT</command>: <programlisting> INSERT INTO films (code, title, did, date_prod, kind) @@ -170,7 +170,7 @@ INSERT INTO films (code, title, did, date_prod, kind) </para> <para> - In the context of <command>INSERT</>, entries of a <command>VALUES</> list + In the context of <command>INSERT</command>, entries of a <command>VALUES</command> list can be <literal>DEFAULT</literal> to indicate that the column default should be used here instead of specifying a value: @@ -182,8 +182,8 @@ INSERT INTO films VALUES </para> <para> - <command>VALUES</> can also be used where a sub-<command>SELECT</> might - be written, for example in a <literal>FROM</> clause: + <command>VALUES</command> can also be used where a sub-<command>SELECT</command> might + be written, for example in a <literal>FROM</literal> clause: <programlisting> SELECT f.* @@ -195,17 +195,17 @@ UPDATE employees SET salary = salary * v.increase WHERE employees.depno = v.depno AND employees.sales >= v.target; </programlisting> - Note that an <literal>AS</> clause is required when <command>VALUES</> - is used in a <literal>FROM</> clause, just as is true for - <command>SELECT</>. It is not required that the <literal>AS</> clause + Note that an <literal>AS</literal> clause is required when <command>VALUES</command> + is used in a <literal>FROM</literal> clause, just as is true for + <command>SELECT</command>. It is not required that the <literal>AS</literal> clause specify names for all the columns, but it's good practice to do so. - (The default column names for <command>VALUES</> are <literal>column1</>, - <literal>column2</>, etc in <productname>PostgreSQL</productname>, but + (The default column names for <command>VALUES</command> are <literal>column1</literal>, + <literal>column2</literal>, etc in <productname>PostgreSQL</productname>, but these names might be different in other database systems.) </para> <para> - When <command>VALUES</> is used in <command>INSERT</>, the values are all + When <command>VALUES</command> is used in <command>INSERT</command>, the values are all automatically coerced to the data type of the corresponding destination column. When it's used in other contexts, it might be necessary to specify the correct data type. If the entries are all quoted literal constants, @@ -218,9 +218,9 @@ WHERE ip_address IN (VALUES('192.168.0.1'::inet), ('192.168.0.10'), ('192.168.1. <tip> <para> - For simple <literal>IN</> tests, it's better to rely on the + For simple <literal>IN</literal> tests, it's better to rely on the <link linkend="functions-comparisons-in-scalar">list-of-scalars</link> - form of <literal>IN</> than to write a <command>VALUES</> + form of <literal>IN</literal> than to write a <command>VALUES</command> query as shown above. The list of scalars method requires less writing and is often more efficient. </para> |