aboutsummaryrefslogtreecommitdiff
path: root/doc/src/sgml/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml/ref')
-rw-r--r--doc/src/sgml/ref/alter_database.sgml2
-rw-r--r--doc/src/sgml/ref/alter_table.sgml18
-rw-r--r--doc/src/sgml/ref/copy.sgml38
-rw-r--r--doc/src/sgml/ref/create_database.sgml2
-rw-r--r--doc/src/sgml/ref/create_foreign_table.sgml2
-rw-r--r--doc/src/sgml/ref/create_index.sgml2
-rw-r--r--doc/src/sgml/ref/create_operator.sgml6
-rw-r--r--doc/src/sgml/ref/create_table.sgml29
-rw-r--r--doc/src/sgml/ref/create_trigger.sgml11
-rw-r--r--doc/src/sgml/ref/merge.sgml39
-rw-r--r--doc/src/sgml/ref/pg_amcheck.sgml12
-rw-r--r--doc/src/sgml/ref/pg_createsubscriber.sgml59
-rw-r--r--doc/src/sgml/ref/pg_dump.sgml31
-rw-r--r--doc/src/sgml/ref/pg_dumpall.sgml30
-rw-r--r--doc/src/sgml/ref/pg_recvlogical.sgml9
-rw-r--r--doc/src/sgml/ref/pg_restore.sgml13
-rw-r--r--doc/src/sgml/ref/pgtesttiming.sgml279
-rw-r--r--doc/src/sgml/ref/pgupgrade.sgml3
-rw-r--r--doc/src/sgml/ref/psql-ref.sgml32
-rw-r--r--doc/src/sgml/ref/security_label.sgml4
-rw-r--r--doc/src/sgml/ref/update.sgml3
21 files changed, 302 insertions, 322 deletions
diff --git a/doc/src/sgml/ref/alter_database.sgml b/doc/src/sgml/ref/alter_database.sgml
index 9da8920e12e..1fc051e11a3 100644
--- a/doc/src/sgml/ref/alter_database.sgml
+++ b/doc/src/sgml/ref/alter_database.sgml
@@ -83,7 +83,7 @@ ALTER DATABASE <replaceable class="parameter">name</replaceable> RESET ALL
must be empty for this database, and no one can be connected to
the database. Tables and indexes in non-default tablespaces are
unaffected. The method used to copy files to the new tablespace
- is affected by the <xref linkend="guc_file_copy_method"/> setting.
+ is affected by the <xref linkend="guc-file-copy-method"/> setting.
</para>
<para>
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index d63f3a621ac..1e4f26c13f6 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -460,8 +460,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<para>
This form adds a new constraint to a table using the same constraint
syntax as <link linkend="sql-createtable"><command>CREATE TABLE</command></link>, plus the option <literal>NOT
- VALID</literal>, which is currently only allowed for foreign key,
- <literal>CHECK</literal> constraints and not-null constraints.
+ VALID</literal>, which is currently only allowed for foreign-key,
+ <literal>CHECK</literal>, and not-null constraints.
</para>
<para>
@@ -469,7 +469,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
existing rows in the table satisfy the new constraint. But if
the <literal>NOT VALID</literal> option is used, this
potentially-lengthy scan is skipped. The constraint will still be
- enforced against subsequent inserts or updates (that is, they'll fail
+ applied against subsequent inserts or updates (that is, they'll fail
unless there is a matching row in the referenced table, in the case
of foreign keys, or they'll fail unless the new row matches the
specified check condition). But the
@@ -591,7 +591,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
This form validates a foreign key, check, or not-null constraint that was
previously created as <literal>NOT VALID</literal>, by scanning the
table to ensure there are no rows for which the constraint is not
- satisfied. If the constraint is not enforced, an error is thrown.
+ satisfied. If the constraint was set to <literal>NOT ENFORCED</literal>, an error is thrown.
Nothing happens if the constraint is already marked valid.
(See <xref linkend="sql-altertable-notes"/> below for an explanation
of the usefulness of this command.)
@@ -852,7 +852,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<para>
<literal>SHARE UPDATE EXCLUSIVE</literal> lock will be taken for
- fillfactor, toast and autovacuum storage parameters, as well as the
+ fillfactor, TOAST and autovacuum storage parameters, as well as the
planner parameter <varname>parallel_workers</varname>.
</para>
</listitem>
@@ -1466,11 +1466,11 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</para>
<para>
- Adding an enforced <literal>CHECK</literal> or <literal>NOT NULL</literal>
+ 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. If a <literal>CHECK</literal>
- constraint is added as <literal>NOT ENFORCED</literal>, the validation will
- not be performed.
+ constraint is added as <literal>NOT ENFORCED</literal>, no verification will
+ be performed.
</para>
<para>
@@ -1485,7 +1485,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</para>
<para>
- Scanning a large table to verify a new foreign key or check constraint
+ Scanning a large table to verify new foreign-key, check, or not-null constraints
can take a long time, and other updates to the table are locked out
until the <command>ALTER TABLE ADD CONSTRAINT</command> command is
committed. The main purpose of the <literal>NOT VALID</literal>
diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 8433344e5b6..c2d1fbc1fbe 100644
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -37,7 +37,7 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
DELIMITER '<replaceable class="parameter">delimiter_character</replaceable>'
NULL '<replaceable class="parameter">null_string</replaceable>'
DEFAULT '<replaceable class="parameter">default_string</replaceable>'
- HEADER [ <replaceable class="parameter">boolean</replaceable> | MATCH ]
+ HEADER [ <replaceable class="parameter">boolean</replaceable> | <replaceable class="parameter">integer</replaceable> | MATCH ]
QUOTE '<replaceable class="parameter">quote_character</replaceable>'
ESCAPE '<replaceable class="parameter">escape_character</replaceable>'
FORCE_QUOTE { ( <replaceable class="parameter">column_name</replaceable> [, ...] ) | * }
@@ -213,6 +213,15 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
</varlistentry>
<varlistentry>
+ <term><replaceable class="parameter">integer</replaceable></term>
+ <listitem>
+ <para>
+ Specifies a non-negative integer value passed to the selected option.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>FORMAT</literal></term>
<listitem>
<para>
@@ -303,16 +312,25 @@ COPY { <replaceable class="parameter">table_name</replaceable> [ ( <replaceable
<term><literal>HEADER</literal></term>
<listitem>
<para>
- Specifies that the file contains a header line with the names of each
- column in the file. On output, the first line contains the column
- names from the table. On input, the first line is discarded when this
- option is set to <literal>true</literal> (or equivalent Boolean value).
- If this option is set to <literal>MATCH</literal>, the number and names
- of the columns in the header line must match the actual column names of
- the table, in order; otherwise an error is raised.
+ On output, if this option is set to <literal>true</literal>
+ (or an equivalent Boolean value), the first line of the output will
+ contain the column names from the table.
+ Integer values <literal>0</literal> and <literal>1</literal> are
+ accepted as Boolean values, but other integers are not allowed for
+ <command>COPY TO</command> commands.
+ </para>
+ <para>
+ On input, if this option is set to <literal>true</literal>
+ (or an equivalent Boolean value), the first line of the input is
+ discarded. If set to a non-negative integer, that number of
+ lines are discarded. If set to <literal>MATCH</literal>, the first line
+ is discarded, and it must contain column names that exactly match the
+ table's columns, in both number and order; otherwise, an error is raised.
+ The <literal>MATCH</literal> value is only valid for
+ <command>COPY FROM</command> commands.
+ </para>
+ <para>
This option is not allowed when using <literal>binary</literal> format.
- The <literal>MATCH</literal> option is only valid for <command>COPY
- FROM</command> commands.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index 640c0425fae..4da8aeebb50 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -140,7 +140,7 @@ CREATE DATABASE <replaceable class="parameter">name</replaceable>
after the creation of the new database. In some situations, this may
have a noticeable negative impact on overall system performance. The
<literal>FILE_COPY</literal> strategy is affected by the <xref
- linkend="guc_file_copy_method"/> setting.
+ linkend="guc-file-copy-method"/> setting.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/create_foreign_table.sgml b/doc/src/sgml/ref/create_foreign_table.sgml
index d08834ac9d2..009fa46532b 100644
--- a/doc/src/sgml/ref/create_foreign_table.sgml
+++ b/doc/src/sgml/ref/create_foreign_table.sgml
@@ -232,7 +232,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<term><literal>INCLUDING COMMENTS</literal></term>
<listitem>
<para>
- Comments for the copied columns, constraints, and indexes will be
+ Comments for the copied columns and constraints will be
copied. The default behavior is to exclude comments, resulting in
the copied columns and constraints in the new table having no
comments.
diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml
index 147a8f7587c..b9c679c41e8 100644
--- a/doc/src/sgml/ref/create_index.sgml
+++ b/doc/src/sgml/ref/create_index.sgml
@@ -814,7 +814,7 @@ Indexes:
leveraging multiple CPUs in order to process the table rows faster.
This feature is known as <firstterm>parallel index
build</firstterm>. For index methods that support building indexes
- in parallel (currently, B-tree and BRIN),
+ in parallel (currently, B-tree, GIN, and BRIN),
<varname>maintenance_work_mem</varname> specifies the maximum
amount of memory that can be used by each index build operation as
a whole, regardless of how many worker processes were started.
diff --git a/doc/src/sgml/ref/create_operator.sgml b/doc/src/sgml/ref/create_operator.sgml
index 3553d364541..d2ffb1b2a50 100644
--- a/doc/src/sgml/ref/create_operator.sgml
+++ b/doc/src/sgml/ref/create_operator.sgml
@@ -23,7 +23,7 @@ PostgreSQL documentation
<synopsis>
CREATE OPERATOR <replaceable>name</replaceable> (
{FUNCTION|PROCEDURE} = <replaceable class="parameter">function_name</replaceable>
- [, LEFTARG = <replaceable class="parameter">left_type</replaceable> ] [, RIGHTARG = <replaceable class="parameter">right_type</replaceable> ]
+ [, LEFTARG = <replaceable class="parameter">left_type</replaceable> ] , RIGHTARG = <replaceable class="parameter">right_type</replaceable>
[, COMMUTATOR = <replaceable class="parameter">com_op</replaceable> ] [, NEGATOR = <replaceable class="parameter">neg_op</replaceable> ]
[, RESTRICT = <replaceable class="parameter">res_proc</replaceable> ] [, JOIN = <replaceable class="parameter">join_proc</replaceable> ]
[, HASHES ] [, MERGES ]
@@ -88,8 +88,8 @@ CREATE OPERATOR <replaceable>name</replaceable> (
<para>
For binary operators, both <literal>LEFTARG</literal> and
- <literal>RIGHTARG</literal> must be defined. For prefix operators only
- <literal>RIGHTARG</literal> should be defined.
+ <literal>RIGHTARG</literal> must be defined. For prefix operators, only
+ <literal>RIGHTARG</literal> must be defined.
The <replaceable class="parameter">function_name</replaceable>
function must have been previously defined using <command>CREATE
FUNCTION</command> and must be defined to accept the correct number
diff --git a/doc/src/sgml/ref/create_table.sgml b/doc/src/sgml/ref/create_table.sgml
index 4a41b2f5530..dc000e913c1 100644
--- a/doc/src/sgml/ref/create_table.sgml
+++ b/doc/src/sgml/ref/create_table.sgml
@@ -448,11 +448,6 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</para>
<para>
- Partitioned tables do not support <literal>EXCLUDE</literal> constraints;
- however, you can define these constraints on individual partitions.
- </para>
-
- <para>
See <xref linkend="ddl-partitioning"/> for more discussion on table
partitioning.
</para>
@@ -929,6 +924,15 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
not other generated columns. Any functions and operators used must be
immutable. References to other tables are not allowed.
</para>
+
+ <para>
+ A virtual generated column cannot have a user-defined type, and the
+ generation expression of a virtual generated column must not reference
+ user-defined functions or types, that is, it can only use built-in
+ functions or types. This applies also indirectly, such as for functions
+ or types that underlie operators or casts. (This restriction does not
+ exist for stored generated columns.)
+ </para>
</listitem>
</varlistentry>
@@ -1162,6 +1166,18 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
exclusion constraint on a subset of the table; internally this creates a
partial index. Note that parentheses are required around the predicate.
</para>
+
+ <para>
+ When establishing an exclusion constraint for a multi-level partition
+ hierarchy, all the columns in the partition key of the target
+ partitioned table, as well as those of all its descendant partitioned
+ tables, must be included in the constraint definition. Additionally,
+ those columns must be compared using the equality operator. These
+ restrictions ensure that potentially-conflicting rows will exist in the
+ same partition. The constraint may also refer to other columns which
+ are not a part of any partition key, which can be compared using any
+ appropriate operator.
+ </para>
</listitem>
</varlistentry>
@@ -1687,7 +1703,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<varlistentry id="reloption-vacuum-truncate" xreflabel="vacuum_truncate">
<term><literal>vacuum_truncate</literal>, <literal>toast.vacuum_truncate</literal> (<type>boolean</type>)
<indexterm>
- <primary><varname>vacuum_truncate</varname> storage parameter</primary>
+ <primary><varname>vacuum_truncate</varname></primary>
+ <secondary>storage parameter</secondary>
</indexterm>
</term>
<listitem>
diff --git a/doc/src/sgml/ref/create_trigger.sgml b/doc/src/sgml/ref/create_trigger.sgml
index 982ab6f3ee4..ed6d206ae71 100644
--- a/doc/src/sgml/ref/create_trigger.sgml
+++ b/doc/src/sgml/ref/create_trigger.sgml
@@ -29,7 +29,7 @@ PostgreSQL documentation
CREATE [ OR REPLACE ] [ CONSTRAINT ] TRIGGER <replaceable class="parameter">name</replaceable> { BEFORE | AFTER | INSTEAD OF } { <replaceable class="parameter">event</replaceable> [ OR ... ] }
ON <replaceable class="parameter">table_name</replaceable>
[ FROM <replaceable class="parameter">referenced_table_name</replaceable> ]
- [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ]
+ [ NOT DEFERRABLE | [ DEFERRABLE ] [ INITIALLY IMMEDIATE | INITIALLY DEFERRED ] ] [ ENFORCED ]
[ REFERENCING { { OLD | NEW } TABLE [ AS ] <replaceable class="parameter">transition_relation_name</replaceable> } [ ... ] ]
[ FOR [ EACH ] { ROW | STATEMENT } ]
[ WHEN ( <replaceable class="parameter">condition</replaceable> ) ]
@@ -322,6 +322,15 @@ UPDATE OF <replaceable>column_name1</replaceable> [, <replaceable>column_name2</
</varlistentry>
<varlistentry>
+ <term><literal>ENFORCED</literal></term>
+ <listitem>
+ <para>
+ This is a noise word. Constraint triggers are always enforced.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><literal>REFERENCING</literal></term>
<listitem>
<para>
diff --git a/doc/src/sgml/ref/merge.sgml b/doc/src/sgml/ref/merge.sgml
index ecbcd8345d8..c2e181066a4 100644
--- a/doc/src/sgml/ref/merge.sgml
+++ b/doc/src/sgml/ref/merge.sgml
@@ -23,37 +23,37 @@ PostgreSQL documentation
<synopsis>
[ WITH <replaceable class="parameter">with_query</replaceable> [, ...] ]
MERGE INTO [ ONLY ] <replaceable class="parameter">target_table_name</replaceable> [ * ] [ [ AS ] <replaceable class="parameter">target_alias</replaceable> ]
-USING <replaceable class="parameter">data_source</replaceable> ON <replaceable class="parameter">join_condition</replaceable>
-<replaceable class="parameter">when_clause</replaceable> [...]
-[ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
- { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
+ USING <replaceable class="parameter">data_source</replaceable> ON <replaceable class="parameter">join_condition</replaceable>
+ <replaceable class="parameter">when_clause</replaceable> [...]
+ [ RETURNING [ WITH ( { OLD | NEW } AS <replaceable class="parameter">output_alias</replaceable> [, ...] ) ]
+ { * | <replaceable class="parameter">output_expression</replaceable> [ [ AS ] <replaceable class="parameter">output_name</replaceable> ] } [, ...] ]
<phrase>where <replaceable class="parameter">data_source</replaceable> is:</phrase>
-{ [ ONLY ] <replaceable class="parameter">source_table_name</replaceable> [ * ] | ( <replaceable class="parameter">source_query</replaceable> ) } [ [ AS ] <replaceable class="parameter">source_alias</replaceable> ]
+ { [ ONLY ] <replaceable class="parameter">source_table_name</replaceable> [ * ] | ( <replaceable class="parameter">source_query</replaceable> ) } [ [ AS ] <replaceable class="parameter">source_alias</replaceable> ]
<phrase>and <replaceable class="parameter">when_clause</replaceable> is:</phrase>
-{ WHEN MATCHED [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_update</replaceable> | <replaceable class="parameter">merge_delete</replaceable> | DO NOTHING } |
- WHEN NOT MATCHED BY SOURCE [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_update</replaceable> | <replaceable class="parameter">merge_delete</replaceable> | DO NOTHING } |
- WHEN NOT MATCHED [ BY TARGET ] [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_insert</replaceable> | DO NOTHING } }
+ { WHEN MATCHED [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_update</replaceable> | <replaceable class="parameter">merge_delete</replaceable> | DO NOTHING } |
+ WHEN NOT MATCHED BY SOURCE [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_update</replaceable> | <replaceable class="parameter">merge_delete</replaceable> | DO NOTHING } |
+ WHEN NOT MATCHED [ BY TARGET ] [ AND <replaceable class="parameter">condition</replaceable> ] THEN { <replaceable class="parameter">merge_insert</replaceable> | DO NOTHING } }
<phrase>and <replaceable class="parameter">merge_insert</replaceable> is:</phrase>
-INSERT [( <replaceable class="parameter">column_name</replaceable> [, ...] )]
-[ OVERRIDING { SYSTEM | USER } VALUE ]
-{ VALUES ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) | DEFAULT VALUES }
+ INSERT [( <replaceable class="parameter">column_name</replaceable> [, ...] )]
+ [ OVERRIDING { SYSTEM | USER } VALUE ]
+ { VALUES ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) | DEFAULT VALUES }
<phrase>and <replaceable class="parameter">merge_update</replaceable> is:</phrase>
-UPDATE SET { <replaceable class="parameter">column_name</replaceable> = { <replaceable class="parameter">expression</replaceable> | DEFAULT } |
- ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = [ ROW ] ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) |
- ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( <replaceable class="parameter">sub-SELECT</replaceable> )
- } [, ...]
+ UPDATE SET { <replaceable class="parameter">column_name</replaceable> = { <replaceable class="parameter">expression</replaceable> | DEFAULT } |
+ ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = [ ROW ] ( { <replaceable class="parameter">expression</replaceable> | DEFAULT } [, ...] ) |
+ ( <replaceable class="parameter">column_name</replaceable> [, ...] ) = ( <replaceable class="parameter">sub-SELECT</replaceable> )
+ } [, ...]
<phrase>and <replaceable class="parameter">merge_delete</replaceable> is:</phrase>
-DELETE
+ DELETE
</synopsis>
</refsynopsisdiv>
@@ -106,10 +106,11 @@ DELETE
to compute and return value(s) based on each row inserted, updated, or
deleted. Any expression using the source or target table's columns, or
the <link linkend="merge-action"><function>merge_action()</function></link>
- function can be computed. When an <command>INSERT</command> or
+ function can be computed. By default, when an <command>INSERT</command> or
<command>UPDATE</command> action is performed, the new values of the target
- table's columns are used. When a <command>DELETE</command> is performed,
- the old values of the target table's columns are used. The syntax of the
+ table's columns are used, and when a <command>DELETE</command> is performed,
+ the old values of the target table's columns are used, but it is also
+ possible to explicitly request old and new values. The syntax of the
<literal>RETURNING</literal> list is identical to that of the output list
of <command>SELECT</command>.
</para>
diff --git a/doc/src/sgml/ref/pg_amcheck.sgml b/doc/src/sgml/ref/pg_amcheck.sgml
index 6bfe28799c4..ef2bdfd19ae 100644
--- a/doc/src/sgml/ref/pg_amcheck.sgml
+++ b/doc/src/sgml/ref/pg_amcheck.sgml
@@ -41,7 +41,7 @@ PostgreSQL documentation
</para>
<para>
- Only ordinary and toast table relations, materialized views, sequences, and
+ Only ordinary and TOAST table relations, materialized views, sequences, and
btree indexes are currently supported. Other relation types are silently
skipped.
</para>
@@ -276,7 +276,7 @@ PostgreSQL documentation
<term><option>--no-dependent-toast</option></term>
<listitem>
<para>
- By default, if a table is checked, its toast table, if any, will also
+ By default, if a table is checked, its TOAST table, if any, will also
be checked, even if it is not explicitly selected by an option
such as <literal>--table</literal> or <literal>--relation</literal>.
This option suppresses that behavior.
@@ -306,9 +306,9 @@ PostgreSQL documentation
<term><option>--exclude-toast-pointers</option></term>
<listitem>
<para>
- By default, whenever a toast pointer is encountered in a table,
+ By default, whenever a TOAST pointer is encountered in a table,
a lookup is performed to ensure that it references apparently-valid
- entries in the toast table. These checks can be quite slow, and this
+ entries in the TOAST table. These checks can be quite slow, and this
option can be used to skip them.
</para>
</listitem>
@@ -368,9 +368,9 @@ PostgreSQL documentation
End checking at the specified block number. An error will occur if the
table relation being checked has fewer than this number of blocks.
This option does not apply to indexes, and is probably only useful when
- checking a single table relation. If both a regular table and a toast
+ checking a single table relation. If both a regular table and a TOAST
table are checked, this option will apply to both, but higher-numbered
- toast blocks may still be accessed while validating toast pointers,
+ TOAST blocks may still be accessed while validating TOAST pointers,
unless that is suppressed using
<option>--exclude-toast-pointers</option>.
</para>
diff --git a/doc/src/sgml/ref/pg_createsubscriber.sgml b/doc/src/sgml/ref/pg_createsubscriber.sgml
index 4b1d08d5f16..bb9cc72576c 100644
--- a/doc/src/sgml/ref/pg_createsubscriber.sgml
+++ b/doc/src/sgml/ref/pg_createsubscriber.sgml
@@ -170,36 +170,6 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>-R <replaceable class="parameter">objtype</replaceable></option></term>
- <term><option>--remove=<replaceable class="parameter">objtype</replaceable></option></term>
- <listitem>
- <para>
- Remove all objects of the specified type from specified databases on the
- target server.
- </para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>publications</literal>:
- The <literal>FOR ALL TABLES</literal> publications established for this
- subscriber are always removed; specifying this object type causes all
- other publications replicated from the source server to be dropped as
- well.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- The objects selected to be dropped are individually logged, including during
- a <option>--dry-run</option>. There is no opportunity to affect or stop the
- dropping of the selected objects, so consider taking a backup of them
- using <application>pg_dump</application>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
<term><option>-s <replaceable class="parameter">dir</replaceable></option></term>
<term><option>--socketdir=<replaceable class="parameter">dir</replaceable></option></term>
<listitem>
@@ -260,6 +230,35 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
+ <term><option>--clean=<replaceable class="parameter">objtype</replaceable></option></term>
+ <listitem>
+ <para>
+ Drop all objects of the specified type from specified databases on the
+ target server.
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>publications</literal>:
+ The <literal>FOR ALL TABLES</literal> publications established for this
+ subscriber are always dropped; specifying this object type causes all
+ other publications replicated from the source server to be dropped as
+ well.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The objects selected to be dropped are individually logged, including during
+ a <option>--dry-run</option>. There is no opportunity to affect or stop the
+ dropping of the selected objects, so consider taking a backup of them
+ using <application>pg_dump</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--config-file=<replaceable class="parameter">filename</replaceable></option></term>
<listitem>
<para>
diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml
index c10bca63e55..2ae084b5fa6 100644
--- a/doc/src/sgml/ref/pg_dump.sgml
+++ b/doc/src/sgml/ref/pg_dump.sgml
@@ -18,7 +18,7 @@ PostgreSQL documentation
<refname>pg_dump</refname>
<refpurpose>
- extract a <productname>PostgreSQL</productname> database into a script file or other archive file
+ export a <productname>PostgreSQL</productname> database as an SQL script or to other formats
</refpurpose>
</refnamediv>
@@ -1134,7 +1134,7 @@ PostgreSQL documentation
<term><option>--no-statistics</option></term>
<listitem>
<para>
- Do not dump statistics.
+ Do not dump statistics. This is the default.
</para>
</listitem>
</varlistentry>
@@ -1277,11 +1277,11 @@ PostgreSQL documentation
</para>
<para>
The data section contains actual table data, large-object
- contents, statistics for tables and materialized views and
- sequence values.
+ contents, sequence values, and statistics for tables,
+ materialized views, and foreign tables.
Post-data items include definitions of indexes, triggers, rules,
statistics for indexes, and constraints other than validated check
- constraints.
+ and not-null constraints.
Pre-data items include all other data definition items.
</para>
</listitem>
@@ -1359,7 +1359,8 @@ PostgreSQL documentation
<listitem>
<para>
Dump only the statistics, not the schema (data definitions) or data.
- Statistics for tables, materialized views, and indexes are dumped.
+ Statistics for tables, materialized views, foreign tables,
+ and indexes are dumped.
</para>
</listitem>
</varlistentry>
@@ -1461,7 +1462,7 @@ PostgreSQL documentation
<term><option>--with-statistics</option></term>
<listitem>
<para>
- Dump statistics. This is the default.
+ Dump statistics.
</para>
</listitem>
</varlistentry>
@@ -1681,14 +1682,14 @@ CREATE DATABASE foo WITH TEMPLATE template0;
</para>
<para>
- By default, <command>pg_dump</command> will include most optimizer
- statistics in the resulting dump file. However, some statistics may not be
- included, such as those created explicitly with <xref
- linkend="sql-createstatistics"/> or custom statistics added by an
- extension. Therefore, it may be useful to run <command>ANALYZE</command>
- after restoring from a dump file to ensure optimal performance; see <xref
- linkend="vacuum-for-statistics"/> and <xref linkend="autovacuum"/> for more
- information.
+ If <option>--with-statistics</option> is specified,
+ <command>pg_dump</command> will include most optimizer statistics in the
+ resulting dump file. However, some statistics may not be included, such as
+ those created explicitly with <xref linkend="sql-createstatistics"/> or
+ custom statistics added by an extension. Therefore, it may be useful to
+ run <command>ANALYZE</command> after restoring from a dump file to ensure
+ optimal performance; see <xref linkend="vacuum-for-statistics"/> and <xref
+ linkend="autovacuum"/> for more information.
</para>
<para>
diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml
index 8c5141d036c..8ca68da5a55 100644
--- a/doc/src/sgml/ref/pg_dumpall.sgml
+++ b/doc/src/sgml/ref/pg_dumpall.sgml
@@ -16,7 +16,10 @@ PostgreSQL documentation
<refnamediv>
<refname>pg_dumpall</refname>
- <refpurpose>extract a <productname>PostgreSQL</productname> database cluster using a specified dump format</refpurpose>
+
+ <refpurpose>
+ export a <productname>PostgreSQL</productname> database cluster as an SQL script or to other formats
+ </refpurpose>
</refnamediv>
<refsynopsisdiv>
@@ -33,7 +36,7 @@ PostgreSQL documentation
<para>
<application>pg_dumpall</application> is a utility for writing out
(<quote>dumping</quote>) all <productname>PostgreSQL</productname> databases
- of a cluster into an archive. The archive contains
+ of a cluster into an SQL script file or an archive. The output contains
<acronym>SQL</acronym> commands that can be used as input to <xref
linkend="app-psql"/> to restore the databases. It does this by
calling <xref linkend="app-pgdump"/> for each database in the cluster.
@@ -567,7 +570,7 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
<term><option>--no-statistics</option></term>
<listitem>
<para>
- Do not dump statistics.
+ Do not dump statistics. This is the default.
</para>
</listitem>
</varlistentry>
@@ -690,7 +693,8 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
<listitem>
<para>
Dump only the statistics, not the schema (data definitions) or data.
- Statistics for tables, materialized views, and indexes are dumped.
+ Statistics for tables, materialized views, foreign tables,
+ and indexes are dumped.
</para>
</listitem>
</varlistentry>
@@ -741,7 +745,7 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
<term><option>--with-statistics</option></term>
<listitem>
<para>
- Dump statistics. This is the default.
+ Dump statistics.
</para>
</listitem>
</varlistentry>
@@ -957,14 +961,14 @@ exclude database <replaceable class="parameter">PATTERN</replaceable>
</para>
<para>
- By default, <command>pg_dumpall</command> will include most optimizer
- statistics in the resulting dump file. However, some statistics may not be
- included, such as those created explicitly with <xref
- linkend="sql-createstatistics"/> or custom statistics added by an
- extension. Therefore, it may be useful to run <command>ANALYZE</command>
- on each database after restoring from a dump file to ensure optimal
- performance. You can also run <command>vacuumdb -a -z</command> to analyze
- all databases.
+ If <option>--with-statistics</option> is specified,
+ <command>pg_dumpall</command> will include most optimizer statistics in the
+ resulting dump file. However, some statistics may not be included, such as
+ those created explicitly with <xref linkend="sql-createstatistics"/> or
+ custom statistics added by an extension. Therefore, it may be useful to
+ run <command>ANALYZE</command> on each database after restoring from a dump
+ file to ensure optimal performance. You can also run <command>vacuumdb -a
+ -z</command> to analyze all databases.
</para>
<para>
diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml
index 63a45c7018a..f68182266a9 100644
--- a/doc/src/sgml/ref/pg_recvlogical.sgml
+++ b/doc/src/sgml/ref/pg_recvlogical.sgml
@@ -79,8 +79,8 @@ PostgreSQL documentation
</para>
<para>
- The <option>--two-phase</option> and <option>--failover</option> options
- can be specified with <option>--create-slot</option>.
+ The <option>--enable-two-phase</option> and <option>--enable-failover</option>
+ options can be specified with <option>--create-slot</option>.
</para>
</listitem>
</varlistentry>
@@ -166,7 +166,7 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
- <term><option>--failover</option></term>
+ <term><option>--enable-failover</option></term>
<listitem>
<para>
Enables the slot to be synchronized to the standbys. This option may
@@ -300,7 +300,8 @@ PostgreSQL documentation
<varlistentry>
<term><option>-t</option></term>
- <term><option>--two-phase</option></term>
+ <term><option>--enable-two-phase</option></term>
+ <term><option>--two-phase</option> (deprecated)</term>
<listitem>
<para>
Enables decoding of prepared transactions. This option may only be specified with
diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml
index 2295df62d03..b649bd3a5ae 100644
--- a/doc/src/sgml/ref/pg_restore.sgml
+++ b/doc/src/sgml/ref/pg_restore.sgml
@@ -18,8 +18,8 @@ PostgreSQL documentation
<refname>pg_restore</refname>
<refpurpose>
- restore a <productname>PostgreSQL</productname> database or cluster
- from an archive created by <application>pg_dump</application> or
+ restore <productname>PostgreSQL</productname> databases from archives
+ created by <application>pg_dump</application> or
<application>pg_dumpall</application>
</refpurpose>
</refnamediv>
@@ -923,7 +923,8 @@ PostgreSQL documentation
<term><option>--with-data</option></term>
<listitem>
<para>
- Dump data. This is the default.
+ Output commands to restore data, if the archive contains them.
+ This is the default.
</para>
</listitem>
</varlistentry>
@@ -932,7 +933,8 @@ PostgreSQL documentation
<term><option>--with-schema</option></term>
<listitem>
<para>
- Dump schema (data definitions). This is the default.
+ Output commands to restore schema (data definitions), if the archive
+ contains them. This is the default.
</para>
</listitem>
</varlistentry>
@@ -941,7 +943,8 @@ PostgreSQL documentation
<term><option>--with-statistics</option></term>
<listitem>
<para>
- Dump statistics. This is the default.
+ Output commands to restore statistics, if the archive contains them.
+ This is the default.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/pgtesttiming.sgml b/doc/src/sgml/ref/pgtesttiming.sgml
index a5eb3aa25e0..afe6a12be4b 100644
--- a/doc/src/sgml/ref/pgtesttiming.sgml
+++ b/doc/src/sgml/ref/pgtesttiming.sgml
@@ -30,11 +30,23 @@ PostgreSQL documentation
<title>Description</title>
<para>
- <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.
+ <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. It simply reads the system clock over and over again
+ as fast as it can for a specified length of time, and then prints
+ statistics about the observed differences in successive clock readings.
+ </para>
+ <para>
+ Smaller (but not zero) differences are better, since they imply both
+ more-precise clock hardware and less overhead to collect a clock reading.
Systems that are slow to collect timing data can give less accurate
<command>EXPLAIN ANALYZE</command> results.
</para>
+ <para>
+ This tool is also helpful to determine if
+ the <varname>track_io_timing</varname> configuration parameter is likely
+ to produce useful results.
+ </para>
</refsect1>
<refsect1>
@@ -60,6 +72,21 @@ PostgreSQL documentation
</varlistentry>
<varlistentry>
+ <term><option>-c <replaceable class="parameter">cutoff</replaceable></option></term>
+ <term><option>--cutoff=<replaceable class="parameter">cutoff</replaceable></option></term>
+ <listitem>
+ <para>
+ Specifies the cutoff percentage for the list of exact observed
+ timing durations (that is, the changes in the system clock value
+ from one reading to the next). The list will end once the running
+ percentage total reaches or exceeds this value, except that the
+ largest observed duration will always be printed. The default
+ cutoff is 99.99.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>-V</option></term>
<term><option>--version</option></term>
<listitem>
@@ -92,205 +119,83 @@ PostgreSQL documentation
<title>Interpreting Results</title>
<para>
- Good results will show most (>90%) individual timing calls take less than
- one microsecond. Average per loop overhead will be even lower, below 100
- nanoseconds. This example from an Intel i7-860 system using a TSC clock
- source shows excellent performance:
-
-<screen><![CDATA[
-Testing timing overhead for 3 seconds.
-Per loop time including overhead: 35.96 ns
-Histogram of timing durations:
- < us % of total count
- 1 96.40465 80435604
- 2 3.59518 2999652
- 4 0.00015 126
- 8 0.00002 13
- 16 0.00000 2
-]]></screen>
+ The first block of output has four columns, with rows showing a
+ shifted-by-one log2(ns) histogram of timing durations (that is, the
+ differences between successive clock readings). This is not the
+ classic log2(n+1) histogram as it counts zeros separately and then
+ switches to log2(ns) starting from value 1.
</para>
-
<para>
- Note that different units are used for the per loop time than the
- histogram. The loop can have resolution within a few nanoseconds (ns),
- while the individual timing calls can only resolve down to one microsecond
- (us).
+ The columns are:
+ <itemizedlist spacing="compact">
+ <listitem>
+ <simpara>nanosecond value that is &gt;= the durations in this
+ bucket</simpara>
+ </listitem>
+ <listitem>
+ <simpara>percentage of durations in this bucket</simpara>
+ </listitem>
+ <listitem>
+ <simpara>running-sum percentage of durations in this and previous
+ buckets</simpara>
+ </listitem>
+ <listitem>
+ <simpara>count of durations in this bucket</simpara>
+ </listitem>
+ </itemizedlist>
</para>
-
- </refsect2>
- <refsect2>
- <title>Measuring Executor Timing Overhead</title>
-
<para>
- When the query executor is running a statement using
- <command>EXPLAIN ANALYZE</command>, individual operations are timed as well
- as showing a summary. The overhead of your system can be checked by
- counting rows with the <application>psql</application> program:
-
-<screen>
-CREATE TABLE t AS SELECT * FROM generate_series(1,100000);
-\timing
-SELECT COUNT(*) FROM t;
-EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
-</screen>
+ The second block of output goes into more detail, showing the exact
+ timing differences observed. For brevity this list is cut off when the
+ running-sum percentage exceeds the user-selectable cutoff value.
+ However, the largest observed difference is always shown.
</para>
-
<para>
- The i7-860 system measured runs the count query in 9.8 ms while
- the <command>EXPLAIN ANALYZE</command> version takes 16.6 ms, each
- processing just over 100,000 rows. That 6.8 ms difference means the timing
- overhead per row is 68 ns, about twice what pg_test_timing estimated it
- would be. Even that relatively small amount of overhead is making the fully
- timed count statement take almost 70% longer. On more substantial queries,
- the timing overhead would be less problematic.
+ The example results below show that 99.99% of timing loops took between
+ 8 and 31 nanoseconds, with the worst case somewhere between 32768 and
+ 65535 nanoseconds. In the second block, we can see that typical loop
+ time is 16 nanoseconds, and the readings appear to have full nanosecond
+ precision.
</para>
- </refsect2>
-
- <refsect2>
- <title>Changing Time Sources</title>
<para>
- On some newer Linux systems, it's possible to change the clock source used
- to collect timing data at any time. A second example shows the slowdown
- possible from switching to the slower acpi_pm time source, on the same
- system used for the fast results above:
-
<screen><![CDATA[
-# cat /sys/devices/system/clocksource/clocksource0/available_clocksource
-tsc hpet acpi_pm
-# echo acpi_pm > /sys/devices/system/clocksource/clocksource0/current_clocksource
-# pg_test_timing
-Per loop time including overhead: 722.92 ns
+Testing timing overhead for 3 seconds.
+Average loop time including overhead: 16.40 ns
Histogram of timing durations:
- < us % of total count
- 1 27.84870 1155682
- 2 72.05956 2990371
- 4 0.07810 3241
- 8 0.01357 563
- 16 0.00007 3
+ <= ns % of total running % count
+ 0 0.0000 0.0000 0
+ 1 0.0000 0.0000 0
+ 3 0.0000 0.0000 0
+ 7 0.0000 0.0000 0
+ 15 4.5452 4.5452 8313178
+ 31 95.4527 99.9979 174581501
+ 63 0.0001 99.9981 253
+ 127 0.0001 99.9982 165
+ 255 0.0000 99.9982 35
+ 511 0.0000 99.9982 1
+ 1023 0.0013 99.9994 2300
+ 2047 0.0004 99.9998 690
+ 4095 0.0000 99.9998 9
+ 8191 0.0000 99.9998 8
+ 16383 0.0002 100.0000 337
+ 32767 0.0000 100.0000 2
+ 65535 0.0000 100.0000 1
+
+Observed timing durations up to 99.9900%:
+ ns % of total running % count
+ 15 4.5452 4.5452 8313178
+ 16 58.3785 62.9237 106773354
+ 17 33.6840 96.6078 61607584
+ 18 3.1151 99.7229 5697480
+ 19 0.2638 99.9867 482570
+ 20 0.0093 99.9960 17054
+...
+ 38051 0.0000 100.0000 1
]]></screen>
</para>
- <para>
- In this configuration, the sample <command>EXPLAIN ANALYZE</command> above
- takes 115.9 ms. That's 1061 ns of timing overhead, again a small multiple
- of what's measured directly by this utility. That much timing overhead
- means the actual query itself is only taking a tiny fraction of the
- accounted for time, most of it is being consumed in overhead instead. In
- this configuration, any <command>EXPLAIN ANALYZE</command> totals involving
- many timed operations would be inflated significantly by timing overhead.
- </para>
-
- <para>
- FreeBSD also allows changing the time source on the fly, and it logs
- information about the timer selected during boot:
-
-<screen>
-# dmesg | grep "Timecounter"
-Timecounter "ACPI-fast" frequency 3579545 Hz quality 900
-Timecounter "i8254" frequency 1193182 Hz quality 0
-Timecounters tick every 10.000 msec
-Timecounter "TSC" frequency 2531787134 Hz quality 800
-# sysctl kern.timecounter.hardware=TSC
-kern.timecounter.hardware: ACPI-fast -> TSC
-</screen>
- </para>
-
- <para>
- Other systems may only allow setting the time source on boot. On older
- Linux systems the "clock" kernel setting is the only way to make this sort
- of change. And even on some more recent ones, the only option you'll see
- for a clock source is "jiffies". Jiffies are the older Linux software clock
- implementation, which can have good resolution when it's backed by fast
- enough timing hardware, as in this example:
-
-<screen><![CDATA[
-$ cat /sys/devices/system/clocksource/clocksource0/available_clocksource
-jiffies
-$ dmesg | grep time.c
-time.c: Using 3.579545 MHz WALL PM GTOD PIT/TSC timer.
-time.c: Detected 2400.153 MHz processor.
-$ pg_test_timing
-Testing timing overhead for 3 seconds.
-Per timing duration including loop overhead: 97.75 ns
-Histogram of timing durations:
- < us % of total count
- 1 90.23734 27694571
- 2 9.75277 2993204
- 4 0.00981 3010
- 8 0.00007 22
- 16 0.00000 1
- 32 0.00000 1
-]]></screen></para>
-
</refsect2>
-
- <refsect2>
- <title>Clock Hardware and Timing Accuracy</title>
-
- <para>
- Collecting accurate timing information is normally done on computers using
- hardware clocks with various levels of accuracy. With some hardware the
- operating systems can pass the system clock time almost directly to
- programs. A system clock can also be derived from a chip that simply
- provides timing interrupts, periodic ticks at some known time interval. In
- either case, operating system kernels provide a clock source that hides
- these details. But the accuracy of that clock source and how quickly it can
- return results varies based on the underlying hardware.
- </para>
-
- <para>
- Inaccurate time keeping can result in system instability. Test any change
- to the clock source very carefully. Operating system defaults are sometimes
- made to favor reliability over best accuracy. And if you are using a virtual
- machine, look into the recommended time sources compatible with it. Virtual
- hardware faces additional difficulties when emulating timers, and there are
- often per operating system settings suggested by vendors.
- </para>
-
- <para>
- The Time Stamp Counter (TSC) clock source is the most accurate one available
- on current generation CPUs. It's the preferred way to track the system time
- when it's supported by the operating system and the TSC clock is
- reliable. There are several ways that TSC can fail to provide an accurate
- timing source, making it unreliable. Older systems can have a TSC clock that
- varies based on the CPU temperature, making it unusable for timing. Trying
- to use TSC on some older multicore CPUs can give a reported time that's
- inconsistent among multiple cores. This can result in the time going
- backwards, a problem this program checks for. And even the newest systems
- can fail to provide accurate TSC timing with very aggressive power saving
- configurations.
- </para>
-
- <para>
- Newer operating systems may check for the known TSC problems and switch to a
- slower, more stable clock source when they are seen. If your system
- supports TSC time but doesn't default to that, it may be disabled for a good
- reason. And some operating systems may not detect all the possible problems
- correctly, or will allow using TSC even in situations where it's known to be
- inaccurate.
- </para>
-
- <para>
- The High Precision Event Timer (HPET) is the preferred timer on systems
- where it's available and TSC is not accurate. The timer chip itself is
- programmable to allow up to 100 nanosecond resolution, but you may not see
- that much accuracy in your system clock.
- </para>
-
- <para>
- Advanced Configuration and Power Interface (ACPI) provides a Power
- Management (PM) Timer, which Linux refers to as the acpi_pm. The clock
- derived from acpi_pm will at best provide 300 nanosecond resolution.
- </para>
-
- <para>
- Timers used on older PC hardware include the 8254 Programmable Interval
- Timer (PIT), the real-time clock (RTC), the Advanced Programmable Interrupt
- Controller (APIC) timer, and the Cyclone timer. These timers aim for
- millisecond resolution.
- </para>
- </refsect2>
</refsect1>
<refsect1>
@@ -298,6 +203,8 @@ Histogram of timing durations:
<simplelist type="inline">
<member><xref linkend="sql-explain"/></member>
+ <member><ulink url="https://wiki.postgresql.org/wiki/Pg_test_timing">Wiki
+ discussion about timing</ulink></member>
</simplelist>
</refsect1>
</refentry>
diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index aeeed297437..5ddf3a8ae92 100644
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -1110,7 +1110,8 @@ psql --username=postgres --file=script.sql postgres
<member><type>regproc</type></member>
<member><type>regprocedure</type></member>
</simplelist>
- (<type>regclass</type>, <type>regrole</type>, and <type>regtype</type> can be upgraded.)
+ (<type>regclass</type>, <type>regdatabase</type>, <type>regrole</type>, and
+ <type>regtype</type> can be upgraded.)
</para>
<para>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index 8f7d8758ca0..95f4cac2467 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1067,8 +1067,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
</listitem>
</varlistentry>
- <varlistentry id="app-psql-meta-command-close">
- <term><literal>\close</literal> <replaceable class="parameter">prepared_statement_name</replaceable></term>
+ <varlistentry id="app-psql-meta-command-close-prepared">
+ <term><literal>\close_prepared</literal> <replaceable class="parameter">prepared_statement_name</replaceable></term>
<listitem>
<para>
@@ -1081,7 +1081,7 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
Example:
<programlisting>
SELECT $1 \parse stmt1
-\close stmt1
+\close_prepared stmt1
</programlisting>
</para>
@@ -1101,7 +1101,16 @@ SELECT $1 \parse stmt1
<listitem>
<para>
Outputs information about the current database connection,
- including TLS-related information if TLS is in use.
+ including SSL-related information if SSL is in use.
+ </para>
+ <para>
+ Note that the <structfield>Client User</structfield> field shows
+ the user at the time of connection, while the
+ <structfield>Superuser</structfield> field indicates whether
+ the current user (in the current execution context) has
+ superuser privileges. These users are usually the same, but they can
+ differ, for example, if the current user was changed with the
+ <command>SET ROLE</command> command.
</para>
</listitem>
</varlistentry>
@@ -3701,7 +3710,7 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
All queries executed while a pipeline is ongoing use the extended
query protocol. Queries are appended to the pipeline when ending with
a semicolon. The meta-commands <literal>\bind</literal>,
- <literal>\bind_named</literal>, <literal>\close</literal> or
+ <literal>\bind_named</literal>, <literal>\close_prepared</literal> or
<literal>\parse</literal> can be used in an ongoing pipeline. While
a pipeline is ongoing, <literal>\sendpipeline</literal> will append
the current query buffer to the pipeline. Other meta-commands like
@@ -3734,6 +3743,10 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
</para>
<para>
+ <command>COPY</command> is not supported while in pipeline mode.
+ </para>
+
+ <para>
Example:
<programlisting>
\startpipeline
@@ -3853,7 +3866,7 @@ SELECT 1 \bind \sendpipeline
(if given) is reached, or the query no longer returns the minimum number
of rows. Wait the specified number of seconds (default 2) between executions.
The default wait can be changed with the variable
- <xref linkend="app-psql-variables-watch-interval"/>).
+ <xref linkend="app-psql-variables-watch-interval"/>.
For backwards compatibility,
<replaceable class="parameter">seconds</replaceable> can be specified
with or without an <literal>interval=</literal> prefix.
@@ -4752,9 +4765,10 @@ bar
<term><varname>WATCH_INTERVAL</varname></term>
<listitem>
<para>
- This variable sets the default interval which <command>\watch</command>
- waits between executing the query. Specifying an interval in the
- command overrides this variable.
+ This variable sets the default interval, in seconds, which
+ <command>\watch</command> waits between executing the query. The
+ default is 2 seconds. Specifying an interval in the command overrides
+ this variable.
</para>
</listitem>
</varlistentry>
diff --git a/doc/src/sgml/ref/security_label.sgml b/doc/src/sgml/ref/security_label.sgml
index e5e5fb483e9..aa45c0af248 100644
--- a/doc/src/sgml/ref/security_label.sgml
+++ b/doc/src/sgml/ref/security_label.sgml
@@ -84,6 +84,10 @@ SECURITY LABEL [ FOR <replaceable class="parameter">provider</replaceable> ] ON
based on object labels, rather than traditional discretionary access control
(DAC) concepts such as users and groups.
</para>
+
+ <para>
+ You must own the database object to use <command>SECURITY LABEL</command>.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 12ec5ba0709..40cca063946 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -57,7 +57,8 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
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.
+ By default, the new (post-update) values of the table's columns are used,
+ but it is also possible to request the old (pre-update) values.
The syntax of the <literal>RETURNING</literal> list is identical to that of the
output list of <command>SELECT</command>.
</para>