From 292f9854ac0f847a1783a7d276e6009b3bdd3e91 Mon Sep 17 00:00:00 2001 From: Justin Pryzby Date: Thu, 28 Mar 2019 18:50:03 -0500 Subject: [PATCH v5 01/12] review docs for pg12dev --- doc/src/sgml/catalogs.sgml | 4 ++-- doc/src/sgml/config.sgml | 14 +++++++------ doc/src/sgml/ddl.sgml | 16 +++++++------- doc/src/sgml/ecpg.sgml | 16 +++++++------- doc/src/sgml/monitoring.sgml | 43 +++++++++++++++++++------------------- doc/src/sgml/perform.sgml | 8 +++---- doc/src/sgml/protocol.sgml | 6 +++--- doc/src/sgml/ref/create_index.sgml | 4 ++-- doc/src/sgml/ref/pg_rewind.sgml | 13 ++++++------ doc/src/sgml/ref/pgbench.sgml | 7 +++---- doc/src/sgml/ref/vacuum.sgml | 6 +++--- doc/src/sgml/runtime.sgml | 4 ++-- doc/src/sgml/sources.sgml | 18 ++++++++-------- doc/src/sgml/xfunc.sgml | 12 +++++------ src/bin/pg_upgrade/check.c | 6 +++--- 15 files changed, 87 insertions(+), 90 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 3428a7c..47482f2 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -3060,7 +3060,7 @@ SCRAM-SHA-256$<iteration count>:&l simplifies ATTACH/DETACH PARTITION operations: the partition dependencies need only be added or removed. Example: a child partitioned index is made partition-dependent - on both the partition table it is on and the parent partitioned + on both the table partition and the parent partitioned index, so that it goes away if either of those is dropped, but not otherwise. The dependency on the parent index is primary, so that if the user tries to drop the child partitioned index, @@ -3123,7 +3123,7 @@ SCRAM-SHA-256$<iteration count>:&l Note that it's quite possible for two objects to be linked by more than one pg_depend entry. For example, a child partitioned index would have both a partition-type dependency on its - associated partition table, and an auto dependency on each column of + associated table partition, and an auto dependency on each column of that table that it indexes. This sort of situation expresses the union of multiple dependency semantics. A dependent object can be dropped without CASCADE if any of its dependencies satisfies diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index aaab1c5..fa8b40a 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -3433,7 +3433,7 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows current when the base backup was taken. The value latest recovers to the latest timeline found in the archive, which is useful in - a standby server. latest is the default. + a standby server. The default is latest. @@ -4195,8 +4195,9 @@ ANY num_sync ( bytea - The handling of the bytea type is also similar to - the VARCHAR. The definition on an array of type + The handling of the bytea type is similar to + the VARCHAR. The definition of an array of type bytea is converted into a named struct for every variable. A declaration like: @@ -1220,9 +1220,8 @@ bytea var[180]; struct bytea_var { int len; char arr[180]; } var; - The member arr hosts binary format - data. It also can handle even '\0' as part of - data unlike VARCHAR. + The member arr stores binary format + data, which can include zero bytes, unlike VARCHAR. The data is converted from/to hex format and sent/received by ecpglib. @@ -7571,8 +7570,7 @@ PREPARE name FROM A literal C string or a host variable containing a preparable - statement, one of the SELECT, INSERT, UPDATE, or - DELETE. + statement (SELECT, INSERT, UPDATE, or DELETE). diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index bf72d0c..7cec551 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -271,13 +271,13 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser Some of the information in the dynamic statistics views shown in is security restricted. - Ordinary users can only see all the information about their own sessions - (sessions belonging to a role that they are a member of). In rows about + Ordinary users can only see all information about their own sessions + (sessions belonging to a role of which they are a member). In rows for other sessions, many columns will be null. Note, however, that the existence of a session and its general properties such as its sessions user and database are visible to all users. Superusers and members of the built-in role pg_read_all_stats (see also ) can see all the information about all sessions. + linkend="default-roles"/>) can see all information about all sessions. @@ -667,7 +667,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser timestamp with time zoneTime when this process' current transaction was started, or null if no transaction is active. If the current - query is the first of its transaction, this column is equal to the + query is the first of its transaction, this is equal to the query_start column. @@ -3603,16 +3603,16 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, partitions_totalbigint - When creating an index on a partitioned table, this column is set to - the total number of partitions on which the index is to be created. + When creating an index on a partitioned table, this is + the total number of partitions to be processed. partitions_done bigint - When creating an index on a partitioned table, this column is set to - the number of partitions on which the index has been completed. + When creating an index on a partitioned table, this is + the number of partitions for which the process is complete. @@ -3650,11 +3650,10 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, building index - The index is being built by the access method-specific code. In this phase, - access methods that support progress reporting fill in their own progress data, - and the subphase is indicated in this column. Typically, + The index is being built by code specific to the access method, and if + it supports progress reporting, this indicates the method's subphase. blocks_total and blocks_done - will contain progress data, as well as potentially + will contain progress data, as may tuples_total and tuples_done. @@ -3739,15 +3738,15 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, VACUUM Progress Reporting - Whenever VACUUM is running, the - pg_stat_progress_vacuum view will contain - one row for each backend (including autovacuum worker processes) that is - currently vacuuming. The tables below describe the information + The pg_stat_progress_vacuum view will contain one + row for each backend that is running VACUUM, including + autovacuum worker processes. + The tables below describe the information that will be reported and provide information about how to interpret it. Progress for VACUUM FULL commands is reported via - pg_stat_progress_cluster - because both VACUUM FULL and CLUSTER - rewrite the table, while regular VACUUM only modifies it + pg_stat_progress_cluster, + because VACUUM FULL rewrites the table, like CLUSTER, + while regular VACUUM only modifies it in place. See . @@ -3931,9 +3930,9 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, CLUSTER Progress Reporting - Whenever CLUSTER or VACUUM FULL is - running, the pg_stat_progress_cluster view will - contain a row for each backend that is currently running either command. + The pg_stat_progress_cluster view will contain a + row for each backend that is running either + CLUSTER or VACUUM FULL. The tables below describe the information that will be reported and provide information about how to interpret it. diff --git a/doc/src/sgml/perform.sgml b/doc/src/sgml/perform.sgml index 8e16583..0e34652 100644 --- a/doc/src/sgml/perform.sgml +++ b/doc/src/sgml/perform.sgml @@ -899,10 +899,10 @@ EXPLAIN ANALYZE SELECT * FROM tenk1 WHERE unique1 < 100 AND unique2 > 9000 Generally, the EXPLAIN output will display details for every plan node which was generated by the query planner. However, there are cases where the executor is able to determine that certain nodes are - not required; currently, the only node types to support this are the - Append and MergeAppend nodes. These - node types have the ability to discard subnodes which they are able to - determine won't contain any records required by the query. It is possible + not required; currently, the only node types to support this are + Append and MergeAppend, which + are able to discard subnodes when it's deduced that + they will not contain any records required by the query. It is possible to determine that nodes have been removed in this way by the presence of a "Subplans Removed" property in the EXPLAIN output. diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml index b20f169..70f7286 100644 --- a/doc/src/sgml/protocol.sgml +++ b/doc/src/sgml/protocol.sgml @@ -1515,7 +1515,7 @@ SELECT 1/0; the server will only accept encrypted packets from the client which are less than 16kB; gss_wrap_size_limit() should be used by the client to determine the size of the unencrypted message which will fit - within this limit and larger messages should be broken up into multiple + within this limit; larger messages should be broken up into multiple gss_wrap() calls. Typical segments are 8kB of unencrypted data, resulting in encrypted packets of slightly larger than 8kB but well within the 16kB maximum. The server can be expected to not send @@ -1531,8 +1531,8 @@ SELECT 1/0; support to PostgreSQL. In this case the connection must be closed, but the frontend might choose to open a fresh connection and proceed without requesting GSSAPI - encryption. Given the length limits specified above, the ErrorMessage can - not be confused with a proper response from the server with an appropriate + encryption. Given the length limits specified above, the ErrorMessage + cannot be confused with a proper response from the server with an appropriate length. diff --git a/doc/src/sgml/ref/create_index.sgml b/doc/src/sgml/ref/create_index.sgml index 629a31e..713e2c3 100644 --- a/doc/src/sgml/ref/create_index.sgml +++ b/doc/src/sgml/ref/create_index.sgml @@ -181,8 +181,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] - Currently, the B-tree and the GiST index access methods support this - feature. In B-tree and the GiST indexes, the values of columns listed + Currently, only the B-tree and GiST index access methods support this + feature. In B-tree and GiST indexes, the values of columns listed in the INCLUDE clause are included in leaf tuples which correspond to heap tuples, but are not included in upper-level index entries used for tree navigation. diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 4d91eeb..f39fe53 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -106,15 +106,14 @@ PostgreSQL documentation - pg_rewind will fail immediately if it finds - files it cannot write directly to. This can happen for example when - the source and the target server use the same file mapping for read-only - SSL keys and certificates. If such files are present on the target server + pg_rewind will fail immediately if it experiences + a write error. This can happen for example when + the source and target server use the same file mapping for read-only + SSL keys and certificates. If such files are present on the target server, it is recommended to remove them before running - pg_rewind. After doing the rewind, some of + pg_rewind. After performing the rewind, some of those files may have been copied from the source, in which case it may - be necessary to remove the data copied and restore back the set of links - used before the rewind. + be necessary to remove them and restore the files removed beforehand. diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index e3b73a4..cc2e533 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -474,10 +474,9 @@ pgbench options d - Because in "prepared" mode pgbench reuses - the parse analysis result for the second and subsequent query - iteration, pgbench runs faster in the - prepared mode than in other modes. + pgbench runs faster in prepared mode because + parse analysis and planning are done only once rather than during each + query. The default is simple query protocol. (See diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml index f9b0fb8..ec2503d 100644 --- a/doc/src/sgml/ref/vacuum.sgml +++ b/doc/src/sgml/ref/vacuum.sgml @@ -215,9 +215,9 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] [ ANALYZE ] [ ). + systems, and that PostgreSQL was built with + GSSAPI support (see ). diff --git a/doc/src/sgml/sources.sgml b/doc/src/sgml/sources.sgml index a339ebb..e869a31 100644 --- a/doc/src/sgml/sources.sgml +++ b/doc/src/sgml/sources.sgml @@ -103,7 +103,7 @@ less -x4 message text. In addition there are optional elements, the most common of which is an error identifier code that follows the SQL spec's SQLSTATE conventions. - ereport itself is just a shell function, that exists + ereport itself is just a shell function that exists mainly for the syntactic convenience of making message generation look like a function call in the C source code. The only parameter accepted directly by ereport is the severity level. @@ -886,10 +886,10 @@ BETTER: unrecognized node type: 42 For example _StaticAssert() and __builtin_constant_p are currently used, even though - they are from newer revisions of the C standard and a - GCC extension respectively. If not available - we respectively fall back to using a C99 compatible replacement that - performs the same checks, but emits rather cryptic messages and do not + they are from a newer revision of the C standard and a + GCC extension, respectively. If not available, in the first case, + we fall back to using a C99 compatible replacement that + performs the same checks, but emits rather cryptic messages; in the second case, we do not use __builtin_constant_p. @@ -948,7 +948,7 @@ MemoryContextSwitchTo(MemoryContext context) Barring special arrangements code in signal handlers may only call async-signal safe functions (as defined in POSIX) and access variables of type volatile sig_atomic_t. A few - functions in postgres are also deemed signal safe, importantly + functions in postgres are also deemed signal safe; specifically, SetLatch(). @@ -969,9 +969,9 @@ handle_sighup(SIGNAL_ARGS) } errno is saved and restored because - SetLatch() might change it. If that were not done - interrupted code that's currently inspecting errno might see the wrong - value. + SetLatch() might change it. If that were not done, + code interrupted by a signal might see the wrong value of + errno. diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index 34a1938..d14457b 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -3364,11 +3364,11 @@ if (!ptr) - By default, a function is just a black box that the - database system knows very little about the behavior of. However, - that means that queries using the function may be executed much less + By default, a function is a black box that the + database system knows very little about, which + means queries calling the function may be executed less efficiently than they could be. It is possible to supply additional - knowledge that helps the planner optimize function calls. + information that helps the planner optimize function calls. @@ -3381,7 +3381,7 @@ if (!ptr) The parallel safety property (PARALLEL UNSAFE, PARALLEL RESTRICTED, or PARALLEL SAFE) must also be specified if you hope - to use the function in parallelized queries. + queries calling the function to be run using the parallel infrastructure. It can also be useful to specify the function's estimated execution cost, and/or the number of rows a set-returning function is estimated to return. However, the declarative way of specifying those two @@ -3393,7 +3393,7 @@ if (!ptr) It is also possible to attach a planner support function to a SQL-callable function (called its target function), and thereby provide - knowledge about the target function that is too complex to be + information about the target function that is too complex to be represented declaratively. Planner support functions have to be written in C (although their target functions might not be), so this is an advanced feature that relatively few people will use. diff --git a/src/bin/pg_upgrade/check.c b/src/bin/pg_upgrade/check.c index 617270f..370c7aa 100644 --- a/src/bin/pg_upgrade/check.c +++ b/src/bin/pg_upgrade/check.c @@ -222,13 +222,13 @@ output_completion_banner(char *analyze_script_file_name, /* Did we copy the free space files? */ if (GET_MAJOR_VERSION(old_cluster.major_version) >= 804) pg_log(PG_REPORT, - "Optimizer statistics are not transferred by pg_upgrade so,\n" - "once you start the new server, consider running:\n" + "Optimizer statistics are not transferred by pg_upgrade.\n" + "Once you start the new server, consider running:\n" " %s\n\n", analyze_script_file_name); else pg_log(PG_REPORT, "Optimizer statistics and free space information are not transferred\n" - "by pg_upgrade so, once you start the new server, consider running:\n" + "by pg_upgrade. Once you start the new server, consider running:\n" " %s\n\n", analyze_script_file_name); -- 2.7.4