29 Commits

Author SHA1 Message Date
Heikki Linnakangas
c5f42daa60 Misc documentation fixes.
- Misc grammar and punctuation fixes.

- Stylistic cleanup: use spaces between function arguments and JSON fields
  in examples. For example "foo(a,b)" -> "foo(a, b)". Add semicolon after
  last END in a few PL/pgSQL examples that were missing them.

- Make sentence that talked about "..." and ".." operators more clear,
  by avoiding to end the sentence with "..". That makes it look the same
  as "..."

- Fix syntax description for HAVING: HAVING conditions cannot be repeated

Patch by Justin Pryzby, per Yaroslav Schekin's report. Backpatch to all
supported versions, to the extent that the patch applies easily.

Discussion: https://www.postgresql.org/message-id/20201005191922.GE17626%40telsasoft.com
2020-10-19 19:28:54 +03:00
Bruce Momjian
953c64e0f6 doc: add commas after 'i.e.' and 'e.g.'
This follows the American format,
https://jakubmarian.com/comma-after-i-e-and-e-g/. There is no intention
of requiring this format for future text, but making existing text
consistent every few years makes sense.

Discussion: https://postgr.es/m/20200825183619.GA22369@momjian.us

Backpatch-through: 9.5
2020-08-31 18:33:37 -04:00
Tom Lane
3d14c174cb Doc: tweak examples to silence line-too-long PDF build warnings.
In one or two places it seemed reasonable to modify the example so as
to shorten its output slightly; but for the most part I just added a
&zwsp; after 67 characters, which is the most we can fit on a line
of monospace text in A4 format.

Discussion: https://postgr.es/m/6916.1589146280@sss.pgh.pa.us
2020-05-14 18:13:08 -04:00
Amit Kapila
d5b6b6515b Fix typos in parallel query docs.
Reported-by: Jon Jensen
Author: Jon Jensen
Reviewed-by: Amit Kapila and Robert Haas
Backpatch-through: 10
Discussion: https://postgr.es/m/nycvar.YSQ.7.76.1912301807510.9899@ybpnyubfg
2020-01-03 10:52:46 +05:30
Peter Eisentraut
122fa9f942 doc: Fix whitespace
Author: Julien Rouhaud <rjuju123@gmail.com>
2019-04-08 22:32:46 +02:00
Thomas Munro
bb16aba50c Enable parallel query with SERIALIZABLE isolation.
Previously, the SERIALIZABLE isolation level prevented parallel query
from being used.  Allow the two features to be used together by
sharing the leader's SERIALIZABLEXACT with parallel workers.

An extra per-SERIALIZABLEXACT LWLock is introduced to make it safe to
share, and new logic is introduced to coordinate the early release
of the SERIALIZABLEXACT required for the SXACT_FLAG_RO_SAFE
optimization, as follows:

The first backend to observe the SXACT_FLAG_RO_SAFE flag (set by
some other transaction) will 'partially release' the SERIALIZABLEXACT,
meaning that the conflicts and locks it holds are released, but the
SERIALIZABLEXACT itself will remain active because other backends
might still have a pointer to it.

Whenever any backend notices the SXACT_FLAG_RO_SAFE flag, it clears
its own MySerializableXact variable and frees local resources so that
it can skip SSI checks for the rest of the transaction.  In the
special case of the leader process, it transfers the SERIALIZABLEXACT
to a new variable SavedSerializableXact, so that it can be completely
released at the end of the transaction after all workers have exited.

Remove the serializable_okay flag added to CreateParallelContext() by
commit 9da0cc35, because it's now redundant.

Author: Thomas Munro
Reviewed-by: Haribabu Kommi, Robert Haas, Masahiko Sawada, Kevin Grittner
Discussion: https://postgr.es/m/CAEepm=0gXGYhtrVDWOTHS8SQQy_=S9xo+8oCxGLWZAOoeJ=yzQ@mail.gmail.com
2019-03-15 17:47:04 +13:00
Thomas Munro
96e98fa260 Proof-reading for documentation.
Somebody accidentally a word.  Back-patch to 9.6.

Reported-by: Justin Pryzby
Discussion: https://postgr.es/m/20180816195431.GA23707%40telsasoft.com
2018-08-17 11:36:34 +12:00
Robert Haas
e80f2b335e Update parallel.sgml for Parallel Append
Patch by me, reviewed by Thomas Munro, in response to a complaint
from Adrien Nayrat.

Discussion: http://postgr.es/m/baa0d036-7349-f722-ef88-2d8bb3413045@anayrat.info
2018-08-01 08:14:05 -04:00
Peter Eisentraut
bcbd940806 Remove dynamic_shared_memory_type=none
PostgreSQL nowadays offers some kind of dynamic shared memory feature on
all supported platforms.  Having the choice of "none" prevents us from
relying on DSM in core features.  So this patch removes the choice of
"none".

Author: Kyotaro Horiguchi <horiguchi.kyotaro@lab.ntt.co.jp>
2018-07-10 18:35:24 +02:00
Bruce Momjian
25468994ca docs: clarify that CREATE TABLE ... _AS_ can be parallelized
CREATE TABLE without AS doesn't have anything to parallelize.
2018-05-10 22:37:26 -04:00
Robert Haas
ddc1f32ee5 doc: Restrictions on InitPlans in parallel queries relaxed.
This updates the documentation for changes originally made in commit
e89a71fb449af2ef74f47be1175f99956cf21524.

Patch by me, reviewed (but not entirely endorsed) by Amit Kapila.

Discussion: http://postgr.es/m/CA+Tgmoa+vupW8V_gBonz6hU7WwN2zJ=UTsVWCVB+rN6vaaXfZw@mail.gmail.com
2018-05-09 15:15:03 -04:00
Robert Haas
f644c3b386 doc: Update parallel join documentation for Parallel Shared Hash.
Thomas Munro

Discussion: http://postgr.es/m/CAEepm=3XdL=+bn3=WQVCCT5wwfAEv-4onKpk+XQZdwDXv6etzA@mail.gmail.com
2018-03-22 13:26:12 -04:00
Peter Eisentraut
3c49c6facb Convert documentation to DocBook XML
Since some preparation work had already been done, the only source
changes left were changing empty-element tags like <xref linkend="foo">
to <xref linkend="foo"/>, and changing the DOCTYPE.

The source files are still named *.sgml, but they are actually XML files
now.  Renaming could be considered later.

In the build system, the intermediate step to convert from SGML to XML
is removed.  Everything is build straight from the source files again.
The OpenSP (or the old SP) package is no longer needed.

The documentation toolchain instructions are updated and are much
simpler now.

Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 09:44:28 -05:00
Peter Eisentraut
c29c578908 Don't use SGML empty tags
For DocBook XML compatibility, don't use SGML empty tags (</>) anymore,
replace by the full tag name.  Add a warning option to catch future
occurrences.

Alexander Lakhin, Jürgen Purtz
2017-10-17 15:10:33 -04:00
Robert Haas
e9baa5e9fa Allow DML commands that create tables to use parallel query.
Haribabu Kommi, reviewed by Dilip Kumar and Rafia Sabih.  Various
cosmetic changes by me to explain why this appears to be safe but
allowing inserts in parallel mode in general wouldn't be.  Also, I
removed the REFRESH MATERIALIZED VIEW case from Haribabu's patch,
since I'm not convinced that case is OK, and hacked on the
documentation somewhat.

Discussion: http://postgr.es/m/CAJrrPGdo5bak6qnPWe8Kpi8g_jfQEs-G4SYmG9y+OFaw2-dPvA@mail.gmail.com
2017-10-05 11:40:48 -04:00
Robert Haas
c1ef4e5cdb Make some more improvements to parallel query documentation.
Many places that mentioned only Gather should also mention Gather
Merge, or should be phrased in a more neutral way.  Be more clear
about the fact that max_parallel_workers_per_gather affects the number
of workers the planner may want to use.  Fix a typo.  Explain how
Gather Merge works.  Adjust wording around parallel scans to be a bit
more clear.  Adjust wording around parallel-restricted operations for
the fact that uncorrelated subplans are no longer restricted.

Patch by me, reviewed by Erik Rijkers

Discussion: http://postgr.es/m/CA+TgmoZsTjgVGn=ei5ht-1qGFKy_m1VgB3d8+Rg304hz91N5ww@mail.gmail.com
2017-08-10 13:22:31 -04:00
Peter Eisentraut
bf6e4c3c82 Trim trailing whitespace 2017-06-12 09:51:18 -04:00
Peter Eisentraut
afd79873a0 Capitalize names of PLs consistently
Author: Daniel Gustafsson <daniel@yesql.se>
2017-04-05 00:38:25 -04:00
Robert Haas
054637d2e0 Document some new parallel query capabilities.
This updates the text for parallel index scan, parallel index-only
scan, parallel bitmap heap scan, and parallel merge join.  It also
expands the discussion of parallel joins slightly.

Discussion: http://postgr.es/m/CA+TgmoZnCUoM31w3w7JSakVQJQOtcuTyX=HLUr-X1rto2=2bjw@mail.gmail.com
2017-03-09 13:06:18 -05:00
Robert Haas
0ede57a1a5 Corrections and improvements to generic parallel query documentation.
David Rowley, reviewed by Brad DeJong, Amit Kapila, and me.

Discussion: http://postgr.es/m/CAKJS1f81fob-M6RJyTVv3SCasxMuQpj37ReNOJ=tprhwd7hAVg@mail.gmail.com
2017-02-14 09:41:18 -05:00
Tom Lane
ff33d1456e Spellcheck: s/descendent/descendant/g
I got a little annoyed by reading documentation paragraphs containing
both spellings within a few lines of each other.  My dictionary says
"descendant" is the preferred spelling, and it's certainly the majority
usage in our tree, so standardize on that.

For one usage in parallel.sgml, I thought it better to rewrite to avoid
the term altogether.
2016-12-23 11:53:35 -05:00
Peter Eisentraut
b645a05fc6 doc: Remove some trailing whitespace
Per discussion, we will not at this time remove trailing whitespace in
psql output displays where it is part of the actual psql output.

From: Vladimir Rusinov <vrusinov@google.com>
2016-12-17 09:35:31 -05:00
Robert Haas
4212cb7326 Fix interaction of parallel query with prepared statements.
Previously, a prepared statement created via a Parse message could get
a parallel plan, but one created with a PREPARE statement could not.
This state of affairs was due to confusion on my (rhaas) part: I
erroneously believed that a CREATE TABLE .. AS EXECUTE statement could
only be performed with a prepared statement by PREPARE, but in fact
one created by a Prepare message works just as well.  Therefore, it
makes no sense to allow parallel query in one case but not the other.

To fix, allow parallel query with all prepared statements, but run
the parallel plan serially (i.e. without workers) in the case of
CREATE TABLE .. AS EXECUTE.  Also, document this.

Amit Kapila and Tobias Bussman, plus an extra sentence of
documentation by me.
2016-12-06 11:11:54 -05:00
Robert Haas
0e50af2453 Assorted documentation improvements for max_parallel_workers.
Commit b460f5d6693103076dc554aa7cbb96e1e53074f9 overlooked a few bits
of documentation that seem like they should mention the new setting.
2016-12-05 11:03:17 -05:00
Fujii Masao
daac8e30eb Fix typo in docs.
Reported-by: Darko Prelec
2016-12-05 20:48:20 +09:00
Tatsuo Ishii
13d3180fd1 Fix typo.
Confirmed by Michael Paquier.
2016-10-14 09:07:33 +09:00
Tatsuo Ishii
b1ee762a61 Fix typo.
Confirmed by Tom Lane.
2016-10-14 07:45:25 +09:00
Robert Haas
248776ea06 Remove spurious word.
Tatsuo Ishii
2016-10-12 17:01:19 -07:00
Robert Haas
60270e5e00 Add more parallel query documentation.
Previously, the individual settings were documented, but there was
no overall discussion of the capabilities and limitations of the
feature.  Add that.

Patch by me, reviewed by Peter Eisentraut and Álvaro Herrera.
2016-09-21 08:37:02 -04:00