The following docs are updated:
- High-availaility section
- pg_basebackup
- pg_receivewal
Per the principle of least privilege, we want to encourage users to
interact with those areas using roles that have replication rights, but
superusers were mentioned first.
Author: Daniel Gustafsson
Reviewed-by: Fujii Masao, Michael Paquier
Discussion: https://postgr.es/m/ECEBD212-7101-41EB-84F3-2F356E4B6401@yesql.se
In commit 33e05f89c5, we have added the option to display WAL usage
statistics in Explain and auto_explain. The display format used two spaces
between each field which is inconsistent with Buffer usage statistics which
is using one space between each field. Change the format to make WAL usage
statistics consistent with Buffer usage statistics.
This commit also changed the usage of "full page writes" to
"full page images" for WAL usage statistics to make it consistent with
other parts of code and docs.
Author: Julien Rouhaud, Amit Kapila
Reviewed-by: Justin Pryzby, Kyotaro Horiguchi and Amit Kapila
Discussion: https://postgr.es/m/CAB-hujrP8ZfUkvL5OYETipQwA=e3n7oqHFU=4ZLxWS_Cza3kQQ@mail.gmail.com
The PDF toolchain defaults to laying out all columns of a table with
equal widths, in contrast to the HTML rendering which automatically
varies the column widths to fit the data. In many places, this
results in very badly laid-out tables, with lots of useless whitespace
in some places and text that overruns its cell in other places.
For tables that have reasonably static content, we can improve
matters by adding <colspec> entries to hand-assign the column widths.
This commit does that for a few of the tables that were worst off;
it eliminates close to 200 "contents ... exceed the available area"
warnings in an A4 PDF build.
I also forced align="left" in these tables, overriding the PDF
toolchain's default which is evidently "justify". (The HTML toolchain
seems to default to that already.) Anyplace where things are tight
enough that we need to worry about this, forced justification tends to
look truly awful.
We had a mishmash of <replaceable>, <replaceable class="parameter">,
and <parameter> markup for operator/function arguments. Use <parameter>
consistently for things that are in fact names of parameters (including
OUT parameters), reserving <replaceable> for things that aren't. The
latter class includes some made-up-by-the-docs type class names, like
"numeric_type", as well as placeholders for arguments that don't have
well-defined types. Possibly we could do better with those categories
as well, but for the moment I'm content not to have parameter names
marked up in different ways in different places.
(This commit aligns the earlier sections of chapter 9 with a policy
that I'd arrived at while working on commit 1ad23335f, which is why
the last few sections need no changes.)
The pg_rewind docs currently assert that the state of the target's
data directory after rewind is equivalent to the source's data
directory. This clarifies the documentation to describe that the base
state is further back in time and that the target's data directory will
include the current state from the source of any copied blocks since the
point of divergence.
This commit also improves the section "How It Works":
- Describe the update of the pg_control file.
- Reorganize the list of files and directories ignored during the
rewind.
Author: James Coleman
Discussion: https://postgr.es/m/CAAaqYe-sgqCos7MXF4XiY8rUPy3CEmaCY9EvfhX-DhPhPBF5_A@mail.gmail.com
The libpq parameters ssl{max|min}protocolversion are renamed to use
underscores, to become ssl_{max|min}_protocol_version. The related
environment variables still use the names introduced in commit ff8ca5f
that added the feature.
Per complaint from Peter Eisentraut (this was also mentioned by me in
the original patch review but the issue got discarded).
Author: Daniel Gustafsson
Reviewed-by: Peter Eisentraut, Michael Paquier
Discussion: https://postgr.es/m/b319e449-318d-e691-4997-1327e166fcc4@2ndquadrant.com
Make the markup a bit less ad-hoc. A function-table cell now contains
several <para> units, and we label the ones that contain function
signatures with role="func_signature". The CSS or FO stylesheets then
key off of that to decide how to set the indentation. A very useful
win from this approach is that we can have more than one signature
entry per table cell, simplifying the documentation of closely-related
operators and functions.
This patch mostly just replaces the markup in the tables I converted so
far. But I did alter a couple of places where multiple signatures were
helpful.
Discussion: https://postgr.es/m/5561.1587922854@sss.pgh.pa.us
This includes the usual amount of editorial cleanup, such as
correcting wrong or less-helpful-than-they-could-be examples.
I moved the two tsvector-updating triggers into "9.28 Trigger
Functions", which seems like a better home for them. (I believe
that section didn't exist when this text was originally written.)
Also rearrange that page a bit for more consistency and less
duplication.
In passing, fix erroneous examples of the results of abbrev(cidr)
in datatype.sgml, and do a bit of copy-editing there.
David Johnston reminded me that the per-point calculations being done
by these operators are equivalent to complex multiplication/division.
(Once I would've recognized that immediately, but it's been too long
since I did any of that sort of math.)
Also put in a footnote mentioning that "rotation" of a box doesn't do
what you might expect, as I'd griped about in the referenced thread.
Discussion: https://postgr.es/m/158110996889.1089.4224139874633222837@wrigleys.postgresql.org
This also makes an attempt to flesh out the docs for some of the more
severely underdocumented geometric operators and functions.
This effort exposed that the point <^ point (point_below) and
point >^ point (point_above) operators are misnamed; they should be
<<| and |>>, because they act like the other operators named that
way and not like the other operators named <^ and >^. But I just
documented them that way; fixing it is matter for another patch.
The haphazard datatype coverage of many of the operators is also
now depressingly obvious.
Discussion: https://postgr.es/m/158110996889.1089.4224139874633222837@wrigleys.postgresql.org
Add a couple of lines to make it explicit that indexes, constraints,
triggers are added, removed, or left alone.
Backpatch to pg11.
Author: Álvaro Herrera <alvherre@alvh.no-ip.org>
Reviewed-by: Justin Pryzby <pryzby@telsasoft.com>
Discussion: https://postgr.es/m/20200421162038.GA18628@alvherre.pgsql
When a partition is detached, any triggers that had been cloned from its
parent were not properly disentangled from its parent triggers.
This resulted in triggers that could not be dropped because they
depended on the trigger in the trigger in the no-longer-parent table:
ALTER TABLE t DETACH PARTITION t1;
DROP TRIGGER trig ON t1;
ERROR: cannot drop trigger trig on table t1 because trigger trig on table t requires it
HINT: You can drop trigger trig on table t instead.
Moreover the table can no longer be re-attached to its parent, because
the trigger name is already taken:
ALTER TABLE t ATTACH PARTITION t1 FOR VALUES FROM (1)TO(2);
ERROR: trigger "trig" for relation "t1" already exists
The former is a bug introduced in commit 86f575948c77. (The latter is
not necessarily a bug, but it makes the bug more uncomfortable.)
To avoid the complexity that would be needed to tell whether the trigger
has a local definition that has to be merged with the one coming from
the parent table, establish the behavior that the trigger is removed
when the table is detached.
Backpatch to pg11.
Author: Justin Pryzby <pryzby@telsasoft.com>
Reviewed-by: Amit Langote <amitlangote09@gmail.com>
Reviewed-by: Álvaro Herrera <alvherre@alvh.no-ip.org>
Discussion: https://www.postgresql.org/message-id/flat/20200408152412.GZ2228@telsasoft.com
Previously in the "Standby Server Operation" section, pg_ctl promote and
protmote_trigger_file were documented as a method to trigger standby
promotion, but pg_promote() function not.
This commit also adds parentheses into <function>pg_promote</function>
in some docs to make it clearer that a function is being referred to.
Author: Masahiro Ikeda
Reviewed-by: Michael Paquier, Laurenz Albe, Tom Lane, Fujii Masao
Discussion: https://postgr.es/m/de0068417a9f4046bac693cbcc00bdc9@oss.nttdata.com
Commit f2fcad27d59c (9.6 era) added the ability to mark objects as
dependent an extension, but forgot to add a way for such dependencies to
be removed. This commit fixes that oversight.
Strictly speaking this should be backpatched to 9.6, but due to lack of
demand we're not doing so at this time.
Discussion: https://postgr.es/m/20200217225333.GA30974@alvherre.pgsql
Reviewed-by: ahsan hadi <ahsan.hadi@gmail.com>
Reviewed-by: Ibrar Ahmed <ibrar.ahmad@gmail.com>
Reviewed-by: Tom Lane <tgl@sss.pgh.pa.us>
Along the way, update the older examples for bytea to use "hex"
output format. That lets us get rid of the lame disclaimer about
how the examples assume bytea_output = escape, which was only half
true anyway because none of the more-recently-added examples had
paid any attention to that.
I took the opportunity to do some copy-editing in this area as well,
and to add some new material such as a note about BETWEEN's syntactical
peculiarities.
Of note is that quite a few of the examples of transcendental functions
needed to be updated, because the displayed output no longer matched
what you get on a modern server. I believe some of these cases are
side-effects of the new Ryu algorithm in float8out. Others appear to be
because the examples predate the addition of type numeric, and were
expecting that float8 calculations would be done although the given
syntax would actually lead to calling the numeric function nowadays.
Jonathan Katz felt that slightly different indentation settings made
for a better-looking result, so sync stylesheet-fo.xsl (for PDF) and
stylesheet.css (for non-website-style HTML) with those choices.
Discussion: https://postgr.es/m/31464.1587156281@sss.pgh.pa.us
The table layout ideas proposed in commit e894c6183 were not as widely
popular as I'd hoped. After discussion, we've settled on a layout
that's effectively a single-column table with cell contents much like a
<varlistentry> description of the function or operator; though we're not
actually using <varlistentry>, because it'd add way too much vertical
space. Instead the effect is accomplished using line-break processing
instructions to separate the description and example(s), plus CSS or FO
customizations to produce indentation of all but the first line in each
cell. While technically this is a bit grotty, it does have the
advantage that we won't need to write nearly as much boilerplate markup.
This patch updates tables 9.30, 9.31, and 9.33 (which were touched by
the previous patch) to the revised style, and additionally converts
table 9.10. A lot of work still remains to do, but hopefully it won't
be too controversial.
Thanks to Andrew Dunstan, Pierre Giraud, Robert Haas, Alvaro Herrera,
David Johnston, Jonathan Katz, Isaac Morland for valuable ideas.
Discussion: https://postgr.es/m/8691.1586798003@sss.pgh.pa.us
Earlier we were inconsistent in allowing the usage of parallel and
full options. Change it such that we disallow them only when they are
combined in a way that we don't support.
In passing, improve the comments in some of the existing tests of parallel
vacuum.
Reported-by: Tushar Ahuja
Author: Justin Pryzby, Amit Kapila
Reviewed-by: Sawada Masahiko, Michael Paquier, Mahendra Singh Thalor and
Amit Kapila
Discussion: https://postgr.es/m/58c8d171-e665-6fa3-a9d3-d9423b694dae%40enterprisedb.com
This commit prevents pg_basebackup from receiving backup_manifest file
when --no-manifest is specified. Previously, when pg_basebackup was
writing a tarfile to stdout, it tried to receive backup_manifest file even
when --no-manifest was specified, and reported an error.
Also remove unused -m option from pg_basebackup.
Also fix typo in BASE_BACKUP command documentation.
Author: Fujii Masao
Reviewed-by: Michael Paquier, Robert Haas
Discussion: https://postgr.es/m/01e3ed3a-8729-5aaa-ca84-e60e3ca59db8@oss.nttdata.com
Now that warnings are enabled across the board, this code that tries to
print an undef variable emits one. Silently printing the empty string
achieves the previous behavior.
Author: Álvaro Herrera <alvherre@alvh.no-ip.org>
Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndquadrant.com>
Discussion: https://postgr.es/m/E1jO1VT-0008Qk-TM@gemulon.postgresql.org
We've had a mixture of the warnings pragma, the -w switch on the shebang
line, and no warnings at all. This patch removes the -w swicth and add
the warnings pragma to all perl sources missing it. It raises the
severity of the TestingAndDebugging::RequireUseWarnings perlcritic
policy to level 5, so that we catch any future violations.
Discussion: https://postgr.es/m/20200412074245.GB623763@rfd.leadboat.com
We've long fought with the draconian space limitations of our
traditional table layout for describing SQL functions and operators.
This commit introduces a new approach, though so far I've only applied
it to a few of those tables. The new way makes use of DocBook's support
for different layouts in different rows of a table, and allows the
descriptions and examples for a function or operator to run to several
lines without as much ugliness and wasted space as before.
The core layout concept is now
Name Signature
Description
Example Example Result
so that a function or operator really has three table rows not one,
but we group them to look like one row by having the name column
have only one entry for all three rows. (Actually, there could be
four or more rows if you wanted to have more than one example, which
is another thing that was painful before but works easily now.)
This is handled by a "morerows" annotation on the name entry, which
isn't perfect (notably, the toolchain is not smart enough to avoid
breaking these row groups across PDF pages) but there seems no better
solution in DocBook. The name column is normally fairly narrow,
allowing plenty of space for the other column(s), and not wasting too
much space when one of the other components runs to multiple lines.
The varying row layout is managed by defining named "spans" and then
tagging entries with a "spanname" of "name", "sig", "desc", "example",
or "exresult". This provides a bit of semantic annotation to go with
the formatting improvement, which seems like a good thing. (It seems
that we have to re-define these spans afresh for each table, which is
annoying, but it's not any worse than the duplication involved in
the table headers. At least that gives us an opportunity to vary the
relative column widths per-table, which is handy since function tables
sometimes need much wider name columns than operator tables.)
Signature entries should be written in the style
<function>fname</function>(<type>typename</type> ...)
<returnvalue>typename</returnvalue>
The <returnvalue> tag produces a right arrow before the result type
name. (I'll document that convention in a user-visible place later.)
While this provides significantly more horizontal space than before
for examples, it's still true that PDF output is a lot narrower than
typical webpage viewing windows, so some examples need to be broken
in places where there is no whitespace. I've added &zwsp; markers in
suitable places to allow the tables to render warning-free in PDF.
I've so far converted only the date/time operator, date/time function,
and enum function tables in sections 9.9 and 9.10; these were chosen
to provide a reasonable sample of the formatting problems that need
to be solved. Assuming that this looks good on the website and doesn't
provoke howls of anguish, I'll work on the other similar tables in the
near future.
There's a moderate amount of new editorial content in this patch along
with the raw formatting changes; for instance I had to write text
descriptions for operators that lacked them. I failed to resist the
temptation to improve some other descriptions and examples, too.
Patch by me, with thanks to Alexander Lakhin for assistance with
figuring out some formatting issues.
Discussion: https://postgr.es/m/9326.1581457869@sss.pgh.pa.us
We already had a couple of places using zero-width spaces for formatting
hackery, and we're going to need more if we ever want the PDF manuals to
look decent. But please let's not write hard-coded Unicode escapes.
We can avoid that by using a custom entity, which also provides a place
to put a teeny bit of documentation about what it is and how to use it.
I'd previously posted a patch using "&break;" for this, but on reflection
that would be horrible to grep for. Instead let's use "&zwsp;", based
on the name of the Unicode symbol ("zero width space").
Discussion: https://postgr.es/m/9326.1581457869@sss.pgh.pa.us
Commit ac8623760 "fixed" a typo in an example of what would happen in
the event of a typo. Restore the original typo and add a comment about
its intentionality. Backpatch to 12 where the error was introduced.
Per report from irc user Nicolás Alvarez.
